gamebook
This MCP server lets an LLM play and control a choose-your-own-adventure gamebook through session-based tools.
begin_adventure – Start a new adventure session and get the opening scene and choices.
choose_action – Move the story forward by selecting one of the offered action/choice IDs.
use – Use an inventory item or a stateful item in the current scene.
examine – Get a description of an inventory item or an item in the current scene.
look_around – Review the current scene and the items present there.
request_hint – Ask for a subtle hint, or set
directtotruefor a stronger clue.check_player_status – Check the player's current health and inventory.
take_item – Pick up an item and add it to the inventory.
drop_item – Remove an inventory item and leave it in the current place.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gamebookStart a new adventure and show me the opening scene."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Gamebook
A minimal choose-your-own-adventure system with a FastAPI book backend and a Python MCP server that exposes the story to an LLM.
Run it
Play the adventure directly in a terminal. This starts the backend automatically if it is not already running:
uv run gamebook-playSelect a story with --story; the current observatory adventure is the default:
uv run gamebook-play --story observatory
uv run gamebook --story observatory
uv run gamebook-backend --story observatoryEach built-in story is defined in a YAML file under src/gamebook/stories and
registered in gamebook.story.STORY_MODULES.
Related MCP server: Integration Quest
Story YAML
Each story file has a start_scene_id and a scenes mapping. A scene defines
its narrative text, items, optional stateful_items, and outgoing edges.
The loader validates the YAML and converts it into the same NetworkX graph and
runtime models used by the game engine.
start_scene_id: hall
scenes:
hall:
title: Hall
context: A locked door leads into the library.
hint: The door needs a key.
items: []
stateful_items:
- id: library_door
name: Door
is_takeable: false
initial_state: Locked
descriptions:
Locked: The Door is Locked.
Unlocked: The Door is Unlocked.
edges:
- id: library_door
destination_scene_id: library
stateful_item_id: library_door
choice: {id: library, description: Enter the library.}
rule:
required_item_states:
- {item_id: library_door, state: Unlocked}
bidirectional: true
reverse:
choice: {id: hall, description: Return to the hall.}
library:
title: Library
context: Dusty shelves fill the room.
hint: The shelves are worth examining.
items: []State predicates use {item_id, state} mappings. Stateful-item transitions use
{from, to}, and an item-use conditional rule can set states and replace the
item's normal action_message when its required states match.
Use story-level stateful_item_groups for rules that depend on a combination of
stateful items, including items in different scenes. Rules are evaluated in order after a group member changes;
the first matching rule applies its effects and optional action_message.
Stories use a NetworkX MultiDiGraph. Each graph node stores a StoryNode
containing the scene text and items, while each directed edge stores the choice,
visibility conditions, traversal rules, and state changes for moving to another
scene. A multigraph allows multiple distinct choices to connect the same pair of
scenes.
Each StoryNode declares its outgoing StoryEdge values. create_story
validates those declarations and builds the graph, expanding a bidirectional
edge into reciprocal directed edges. The reciprocal edges share one stable edge
ID; when supplied with a non-takeable StatefulItem, its mutable state is stored
once per adventure and is therefore visible from both connected scenes. The
graph remains a shared story template and never stores player session state.
Enter a choice number to move through the story. Other commands include
use <item> [on <target>], examine <item>, take <item>, drop <item>, inventory, look,
hint, hint direct,
restart, and quit.
Set requires_target: true on an item to require the on <target> form.
Start the book backend and Streamable HTTP MCP server together:
uv run gamebookDocker
Build the image and start both the MCP server and backend:
make build
make runThe MCP server is available at http://localhost:8000/mcp; the backend is
available at http://localhost:8001. Set STORY to choose a registered story,
for example make run STORY=observatory.
Start the terminal player in a container with:
make playThe MCP endpoint is http://localhost:8000/mcp. It listens on all WSL network
interfaces so applications running on Windows can connect to it. The backend
listens internally at http://127.0.0.1:8001; its interactive API docs are at
http://127.0.0.1:8001/docs.
Configure LM Studio's mcp.json to connect to the already-running server:
{
"mcpServers": {
"gamebook": {
"url": "http://localhost:8000/mcp"
}
}
}VS Code is configured separately to launch gamebook-mcp over stdio from
.vscode/mcp.json. Open the MCP Servers view or run MCP: List Servers, then
start gamebook to use or debug it. The HTTP backend must also be running for
tools launched this way.
For development, the components can also run separately:
uv run gamebook-backend
uv run gamebook-mcpPoint the MCP bridge at another backend by setting GAMEBOOK_BACKEND_URL.
MCP tools
begin_adventurestarts a session and returns the opening scene.choose_actionsends one of the offered choice IDs to the backend.useuses an inventory item or a stateful item in the current scene.examinedescribes an inventory item or an item in the current scene.look_aroundreturns the current scene and items present there.request_hintasks the backend for a subtle or direct clue.check_inventoryreturns the player's health and inventory.take_itemmoves an item from the current place into the player's inventory.drop_itemmoves an inventory item into the player's current place.
Run the tests with uv run pytest.
Available Tools
9 toolsbegin_adventureB
Begin a new adventure and receive its opening context and choices.
| Name | Required | Description | Default |
|---|---|---|---|
| adventure_session_id | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| title | Yes | |
| choices | Yes | |
| context | Yes | |
| message | No | |
| scene_id | Yes | |
| is_ending | No | |
| adventure_session_id | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. It mentions receiving opening context and choices but does not say whether beginning a new adventure creates or overwrites a session, or what happens if an existing adventure_session_id is supplied. This is a material gap for a state-changing, session-based tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tight sentence with no filler. The core action and expected outcome are front-loaded, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has one optional parameter whose semantics are unexplained, and the absence of annotations leaves side effects and prerequisites unclear. While an output schema exists, the description alone does not tell an agent whether to start fresh, carry over a session, or expect destructive behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description never mentions adventure_session_id. The parameter name hints at session identity, but the description does not clarify whether null starts a fresh adventure or an ID resumes/restarts one, leaving the sole parameter ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Begin') with a clear resource ('a new adventure') and states the expected output ('opening context and choices'). It is immediately distinguishable from sibling action tools like choose_action, examine, and look_around.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that this tool is the entry point before the action-oriented sibling tools, but it never explicitly states when to use it or how to choose between passing null and an adventure_session_id. No alternatives or exclusions are mentioned, so usage guidance relies on inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
check_player_statusB
Check the player's current health and inventory.
| Name | Required | Description | Default |
|---|---|---|---|
| adventure_session_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| health | Yes | |
| message | No | |
| inventory | Yes | |
| adventure_session_id | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for disclosing side effects and call semantics. 'Check' suggests a read-only operation, but the description does not explicitly state that calling it has no game state impact, does not consume a turn, or can be safely invoked at any time. This is a meaningful gap for an adventure-game context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single succinct sentence that immediately conveys the tool's core purpose. There is no filler, and the most important information ('current health and inventory') is front-loaded. For a simple tool, this is appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The presence of an output schema reduces the need to document return values, but the description still lacks crucial contextual details: it does not explain the adventure_session_id parameter, whether the tool is a free action or costs a turn, or how this status check fits into the broader adventure flow. For a tool with no annotations and low schema coverage, this leaves too much for the agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not mention adventure_session_id at all. The parameter name is somewhat self-explanatory, but the description provides no guidance on how to obtain a valid session ID, what format it should be in, or why it is needed. Since coverage is low, the description should compensate, but it does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Check') and a clear resource ('the player's current health and inventory'). This distinguishes it from siblings like take_item, drop_item, and look_around, which operate on the environment or inventory items rather than the player's internal state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: whenever the agent needs the player's health or inventory state. However, it does not explicitly state when not to use it or mention alternatives, such as using 'examine' for inspecting objects or 'look_around' for the environment. Usage context is implied but not elaborated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
choose_actionC
Choose one of the action IDs offered by the current scene.
| Name | Required | Description | Default |
|---|---|---|---|
| choice_id | Yes | ||
| adventure_session_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| title | Yes | |
| choices | Yes | |
| context | Yes | |
| message | No | |
| scene_id | Yes | |
| is_ending | No | |
| adventure_session_id | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of explaining behavior, but it only states that a choice is made. It does not disclose whether the choice advances the scene, whether it is reversible, whether the session state changes, or what response shape to expect beyond the existence of an output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler. It front-loads the core action, though it could benefit from a short second sentence clarifying the source of action IDs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is fairly simple and an output schema exists, but the description leaves important operational gaps: where action IDs come from, whether adventure_session_id is required from context, and what selecting an action triggers. Given two required parameters and zero schema coverage, this is not complete enough for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for undocumented parameters. It only lightly hints at choice_id through 'action IDs', which helps slightly, but it completely fails to explain adventure_session_id, its format, or how it relates to the current scene.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies a clear verb ('Choose') and resource ('action IDs offered by the current scene'), so an agent can infer this selects from available scene actions. It does not explicitly contrast with sibling tools like use or examine, but the wording is specific enough to avoid major confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied: this tool should be used when the current scene offers action IDs and the agent must pick one. However, there is no explicit guidance on when not to use it or how it relates to siblings, such as whether use is for applying items versus selecting a narrative action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
drop_itemC
Drop an inventory item in the player's current place.
| Name | Required | Description | Default |
|---|---|---|---|
| item_name | Yes | ||
| adventure_session_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| health | Yes | |
| message | No | |
| inventory | Yes | |
| adventure_session_id | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden of behavioral disclosure. It only states the action and fails to mention side effects such as removing the item from the player's inventory, whether the action is reversible, what happens to the item in the place, or whether any validation occurs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short, well-structured sentence with no redundant wording. The verb and object are front-loaded, making the core purpose immediately visible.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although the tool is simple and has an output schema, the description leaves key operational details unaddressed: how the item is identified, what session context is required, what side effects occur, and when this action is permissible. The absence of annotations makes this a notable gap for an agent invoking a mutating action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the undocumented parameters. It gives minimal context for item_name and none for adventure_session_id beyond its name; the meaning of the session identifier and its relationship to the current place is left entirely to inference.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Drop'), a resource ('an inventory item'), and a location ('in the player's current place'), making the action clear. It distinguishes itself from siblings like take_item and use by naming the drop operation explicitly, though it does not directly reference any sibling tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as take_item, use, or examine. The wording implies it should be used to discard a held item, but no explicit context, prerequisites, or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
examineB
Examine an inventory item or an item present in the current scene.
| Name | Required | Description | Default |
|---|---|---|---|
| item_name | Yes | ||
| adventure_session_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| message | No | |
| item_name | Yes | |
| description | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not state whether examining is read-only, whether it changes game state, what happens when the item is absent, or whether scene vs. inventory items behave differently.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler, and the verb-object structure front-loads the core purpose. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core purpose and item scope well, and an output schema exists to handle return-value documentation. However, missing parameter explanation and absent usage guidance leave meaningful gaps, particularly around the required adventure_session_id.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It clarifies that item_name can refer to either an inventory item or a current scene item, but it says nothing about adventure_session_id, expected formats, or how the two parameters relate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description pairs the verb "Examine" with specific resource types: "an inventory item or an item present in the current scene." This clearly distinguishes the tool from scene-level look_around and mutating actions like take_item, drop_item, or use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that examine should be used when an agent wants details about a specific item, but it gives no explicit when-to-use or when-not-to-use guidance relative to siblings like look_around or use. The boundary is inferable from sibling names, but the description does not state it directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
look_aroundB
Review the current place, including any items present there.
| Name | Required | Description | Default |
|---|---|---|---|
| adventure_session_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| title | Yes | |
| choices | Yes | |
| context | Yes | |
| message | No | |
| scene_id | Yes | |
| is_ending | No | |
| adventure_session_id | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden of behavioral disclosure. It only says 'review', which implies a read-only observation, but does not explicitly state that it has no side effects, whether hidden items are revealed, or whether a turn is consumed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence with no redundant phrasing. The key action and scope are front-loaded, and 'including any items present there' adds useful specificity without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple exploration tool with an output schema, the description gives a usable baseline. However, the lack of any relation to sibling tools such as examine, and the absence of behavioral caveats, leaves some context incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not mention adventure_session_id or its role. While the parameter name is self-explanatory, the description adds no meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Review') and resource ('current place') and adds that items present are included. This clearly distinguishes it from tools like take_item or use, but does not explicitly contrast it with the similar examine sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'current place' implies it is for when the agent wants an overview of the current surroundings, but it provides no explicit guidance about when to prefer look_around over examine or other siblings. Usage context is implied, not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
request_hintA
Request a subtle hint, or set direct to true for a stronger clue.
| Name | Required | Description | Default |
|---|---|---|---|
| direct | No | ||
| adventure_session_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| hint | Yes | |
| strength | Yes | |
| adventure_session_id | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses that 'direct' produces a stronger clue, which is useful, but it does not state side effects, limits on hint requests, or whether the hint is read-only. It is minimally transparent but has gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence conveys the core action and parameter effect without filler. Every word contributes to understanding the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and has an output schema, so return values need not be spelled out. However, the description omits the session context and any constraints around hint availability, leaving context to be inferred from the required 'adventure_session_id' and the adventure-themed siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It clarifies the non-obvious 'direct' boolean ('stronger clue') but does not explain 'adventure_session_id', though that parameter's title is reasonably self-explanatory. The required parameter is not described beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('Request a subtle hint') and clearly distinguishes the two modes via the 'direct' flag. It also stands apart from all sibling action tools, none of which are hint-related.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for obtaining hints during an adventure, but it never states when to prefer it, when not to use it, or how it relates to sibling tools. No explicit usage conditions are given; the use case is inferred from the name and wording.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
take_itemB
Take an item using its exact name; failures list the available item names.
| Name | Required | Description | Default |
|---|---|---|---|
| item_name | Yes | ||
| adventure_session_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| health | Yes | |
| message | No | |
| inventory | Yes | |
| adventure_session_id | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does add one useful behavioral trait: failures list available item names. But it does not disclose the core side effect of taking an item, whether the action is reversible, what prerequisites exist, or what happens on success.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence delivers the core action and a useful failure behavior. No extra words or repeated schema information; the structure is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description is thin for a state-changing game action. It does not clarify what taking an item accomplishes, when the action is valid, how the available names are returned, or how it relates to sibling actions like use and drop_item. An agent needs more context to call this reliably.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for both parameters. It clarifies that item_name must be the exact name, but it says nothing about adventure_session_id, which is also required. The failure behavior partially informs item_name usage but leaves the session parameter unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Take an item using its exact name'. It is distinguishable from siblings like use, examine, and drop_item by the semantics of taking, though it does not explicitly name or contrast them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: when the player wants to take an item, and it emphasizes using the exact name. However, it does not explicitly say when not to use it or how it differs from use, examine, or drop_item, leaving routing partly to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
useB
Use an inventory item or a stateful item present in the current scene.
| Name | Required | Description | Default |
|---|---|---|---|
| item_name | Yes | ||
| adventure_session_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| title | Yes | |
| choices | Yes | |
| context | Yes | |
| message | No | |
| scene_id | Yes | |
| is_ending | No | |
| adventure_session_id | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full disclosure burden. It reveals an item constraint (inventory or statefil in scene) but does not state what 'using' does—whether the item is consumed, whether the scene changes, or what side effects occur. An agent cannot predict the tool's behavior beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single concise sentence with no filler; the core constraint is front-loaded. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a state-changing tool with two required parameters, the description leaves out usage selection and parameter semantics, and it does not illuminate behavioral outcomes. However, the presence of an output schema mitigates the need to document return values, so the description is minimally viable but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description never mentions item_name or adventure_session_id. item_name is weakly inferable from 'inventory item,' but adventure_session_id is entirely unexplained, forcing the agent to guess its purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action ('use') and a precise scope ('an inventory item or a stateful item present in the current scene'), which clearly distinguishes it from siblings like take_item, drop_item, and examine. The verb-plus-resource pattern makes the tool's purpose immediately intelligible.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that 'use' is appropriate when an item should be consumed or activated, but it never explicitly states when to prefer this tool over examine, take_item, or drop_item. No when/when-not guidance is provided, only the inherent meaning of the verb.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
9 tool updates
v0.1.0- First observed
begin_adventure - First observed
check_player_status - First observed
choose_action - First observed
drop_item - First observed
examine - First observed
look_around - First observed
request_hint - First observed
take_item - First observed
use
TDQS
Most tools map cleanly to distinct actions: starting, choosing, examining, looking, using, taking, dropping, hinting, and checking status. Minor overlap exists between look_around and examine since both inspect the current environment, but their intended purposes remain distinguishable.
The naming pattern is mostly verb_noun with clear action-oriented names like begin_adventure, take_item, and drop_item. The bare verbs 'use' and 'examine' deviate slightly from the pattern, but they are still intuitive and readable.
Nine tools is well-scoped for a gamebook server, covering the core interaction loop without unnecessary bloat. Each tool serves a clear gameplay purpose, and the count feels appropriate for the domain.
The tool set covers the core interactive fiction lifecycle: starting, choosing, looking, examining, using, taking, dropping, hinting, and status tracking. A minor gap is the lack of a dedicated way to refetch the current scene's available actions without beginning or choosing, which could leave agents stuck if context is lost.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
- mcpOAuthco.aistoryhub
Remote MCP server for AIStoryHub: stories, chapters, story bible, Voiceprints, AI generation.
Free blind-play night-fishing game over MCP. Deterministic engine, zero LLM calls, save codes.
MCP server for AI dialogue using various LLM models via AceDataCloud
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to play interactive fiction games (Glulx and Z-machine) through the Model Context Protocol, with automatic save/restore and optional journaling mode.MIT
- AlicenseAqualityDmaintenanceEnables playing a Workato-themed text-based RPG through MCP tools, allowing users to explore dungeons, battle enemies, and manage character progression in an integration-themed adventure.151MIT
- AlicenseNot gradedqualityDmaintenanceEnables LLM-driven text game state management by exposing MCP tools for managing players, locations, items, entities, and abstract concepts.MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI to act as Game Master for tabletop RPGs with deterministic dice, five-tier outcomes, FitD-style stress, combat tracking, clocks, investigations, NPC relationships, and world generation via 134 tools over MCP.2MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/bruceweir/gamebook'
If you have feedback or need assistance with the MCP directory API, please join our Discord server