RPG Maker MZ MCP Server
Click on "Deploy 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., "@RPG Maker MZ MCP ServerCreate a warrior character named Roland with high attack."
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.
🎮 RPG Maker MZ MCP Server
A stable, well-tested Model Context Protocol server that lets AI assistants like Claude create and edit RPG Maker MZ projects through natural language.
Why another one? Existing RPG Maker MZ MCP servers on GitHub suffer from critical issues — stdout pollution breaking the MCP protocol, wrong file extensions, no atomic writes, no tests, and outdated SDKs. This project was built from scratch to fix all of them.
✨ Features
Feature | This Project | Others |
Atomic file writes ( | ✅ | ❌ |
Auto | ✅ | ❌ |
Zod schema validation on reads | ✅ | ❌ |
stderr-only logging (no stdout pollution) | ✅ | ❌ |
Correct | ✅ | ❌ |
Generic | ✅ | ❌ |
Unit & integration tests (42 tests) | ✅ | ❌ |
MCP SDK v1.26+ | ✅ | ❌ |
Event editing with human-readable commands | ✅ | Partial |
AI scenario generation tools | ✅ | ❌ |
Related MCP server: godot-mcp-pilot
🛠 Available Tools (23 total)
Project Management (4)
Tool | Description |
| Load an existing RPG Maker MZ project |
| Create a new project with all default data files |
| Get project stats (maps, actors, items, etc.) |
| List images and audio files in the project |
Database CRUD (6 tools × 8 entity types)
Unified tools that work with actors, classes, skills, items, weapons, armors, enemies, and states:
Tool | Description |
| List all entities of a given type |
| Get entity details by ID |
| Create a new entity with Zod validation |
| Partial update of an existing entity |
| Delete an entity (protects system defaults) |
| Search by keyword across name/description |
Map Management (5)
Tool | Description |
| List all maps with hierarchy |
| Create a new map with size, tileset, BGM |
| Get map details including events |
| Update map properties |
| Delete a map |
Event Editing (5)
Tool | Description |
| List events on a map |
| Create a new event at a position |
| Update event properties |
| Add commands using human-readable format |
| Delete an event |
40+ supported command types including show_text, show_choices, transfer_player, control_switches, play_bgm, battle_processing, shop_processing, and more.
AI Scenario Generation (3)
Tool | Description |
| Generate a game scenario outline from a theme |
| Generate NPC dialogue as event commands |
| Design a quest with objectives and rewards |
These tools leverage the AI's own capabilities — no external API calls needed.
📦 Installation
# Clone the repository
git clone https://github.com/a951753abc/rpgmaker-mz-mcp.git
cd rpgmaker-mz-mcp
# Install dependencies
npm install
# Build
npm run build
# Verify (42 tests should pass)
npm test⚙️ Configuration
Claude Code (CLI)
Create a .mcp.json file in your project directory:
{
"mcpServers": {
"rpgmaker-mz": {
"command": "node",
"args": ["/path/to/rpgmaker-mz-mcp/dist/index.js"]
}
}
}Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"rpgmaker-mz": {
"command": "node",
"args": ["/path/to/rpgmaker-mz-mcp/dist/index.js"]
}
}
}💬 Usage Examples
Once the MCP server is connected, talk to Claude naturally:
You: Load my RPG Maker MZ project at /Users/me/Games/MyRPG
You: Create a warrior character named "Roland" with high attack
You: Create a 20x15 village map called "Oakwood Village" with Town1 BGM
You: Add an NPC shopkeeper on map 2 at position (8, 6)
You: Add dialogue to the shopkeeper: "Welcome! Take a look at my wares."
You: Generate a quest about rescuing a kidnapped princess
You: Create a healing potion item that restores 200 HP🏗 Architecture
src/
├── index.ts # MCP Server entry point (stdio transport)
├── logger.ts # stderr-only logger
├── core/
│ ├── file-handler.ts # Atomic writes + backups + Zod validation
│ ├── project-manager.ts # Project loading / validation
│ ├── database-manager.ts # Generic CRUD for all entity types
│ └── version-sync.ts # System.json versionId auto-sync
├── schemas/
│ ├── database.ts # Zod schemas for 8 entity types
│ ├── map.ts # Map & audio schemas
│ ├── event.ts # Event & command schemas + converter
│ └── system.ts # System.json schema
├── tools/
│ ├── project-tools.ts # 4 project management tools
│ ├── database-tools.ts # 6 database CRUD tools
│ ├── map-tools.ts # 5 map management tools
│ ├── event-tools.ts # 5 event editing tools
│ └── scenario-tools.ts # 3 AI scenario tools
└── templates/
└── defaults.ts # RPG Maker MZ default data templatesKey Design Decisions
Atomic writes: Write to
.tmp→fs.rename()to target. Rename is atomic on the same filesystem, preventing data corruption from partial writes.Auto backup: Every write creates a
.bakfile before overwriting, enabling easy recovery.Zod validation: All JSON reads are validated through Zod schemas instead of unsafe
as Ttype assertions.Generic DatabaseManager<T>: One class handles CRUD for all 8 entity types, eliminating code duplication.
stderr-only logging: MCP uses stdout for JSON-RPC. Any
console.logwould corrupt the protocol. We useconsole.errorexclusively.Version sync: Every data file modification bumps
System.jsonversionId, forcing RPG Maker MZ editor to reload.
🧪 Development
# Run tests
npm test
# Watch mode
npm run test:watch
# Build
npm run build
# Dev mode (auto-rebuild on changes)
npm run devRuntime Dependencies (minimal)
Package | Purpose |
| MCP protocol implementation |
| Schema validation |
That's it. Just 2 runtime dependencies.
📄 License
This project is licensed under the GNU General Public License v3.0.
You are free to use, modify, and distribute this software, provided that derivative works are also distributed under the same license.
繁體中文
簡介
一個穩定、經過完整測試的 Model Context Protocol 伺服器,讓 Claude 等 AI 助手能透過自然語言建立和編輯 RPG Maker MZ 專案。
為什麼要重新開發? GitHub 上現有的 RPG Maker MZ MCP Server 都有嚴重問題 — stdout 污染導致 MCP 協議損壞、副檔名錯誤、沒有原子寫入、沒有測試、SDK 過時。本專案從頭開發,解決了所有已知問題。
特色
原子寫入:先寫入
.tmp暫存檔,再用fs.rename()覆蓋目標,防止寫入中斷導致資料損壞自動備份:每次寫入前自動建立
.bak備份檔Zod 驗證:讀取 JSON 時透過 Zod schema 驗證,取代不安全的
as T型別斷言泛型資料庫管理器:一個
DatabaseManager<T>處理所有 8 種實體的 CRUD,消除重複程式碼stderr 日誌:MCP 使用 stdout 進行 JSON-RPC 通訊,任何
console.log都會破壞協議。本專案只用console.error版本同步:每次修改資料檔案後自動更新
System.json的versionId,強制 RPG Maker MZ 編輯器重新載入
可用工具(共 23 個)
類別 | 工具數 | 說明 |
專案管理 | 4 | 載入 / 建立 / 查詢專案資訊 / 列出素材資源 |
資料庫 CRUD | 6 | 列出 / 取得 / 新增 / 更新 / 刪除 / 搜尋(支援角色、職業、技能、道具、武器、防具、敵人、狀態) |
地圖管理 | 5 | 列出 / 建立 / 查看 / 更新 / 刪除地圖 |
事件編輯 | 5 | 列出 / 建立 / 更新 / 新增指令 / 刪除事件(支援 40+ 種人類可讀指令格式) |
AI 劇情生成 | 3 | 生成遊戲劇情大綱 / NPC 對話 / 任務設計 |
使用範例
連接 MCP Server 後,用自然語言跟 Claude 對話即可:
你:載入我的 RPG Maker MZ 專案,路徑是 /Users/me/Games/MyRPG
你:建立一個戰士角色,名字叫「羅蘭」,攻擊力要高
你:建立一張 20x15 的村莊地圖,叫做「橡木村」,背景音樂用 Town1
你:在地圖 2 的座標 (8, 6) 放一個 NPC 商人
你:幫商人加一段對話:「歡迎光臨!請看看我的商品。」
你:幫我設計一個拯救被綁架公主的任務
你:建立一個回復 200 HP 的治療藥水安裝與設定
git clone https://github.com/a951753abc/rpgmaker-mz-mcp.git
cd rpgmaker-mz-mcp
npm install
npm run build
npm test # 42 個測試應全部通過在你的專案目錄建立 .mcp.json:
{
"mcpServers": {
"rpgmaker-mz": {
"command": "node",
"args": ["/path/to/rpgmaker-mz-mcp/dist/index.js"]
}
}
}日本語
概要
安定性が高く、十分にテスト済みの Model Context Protocol サーバーです。Claude などの AI アシスタントが自然言語で RPG Maker MZ(RPGツクールMZ)のプロジェクトを作成・編集できるようにします。
なぜ新しく開発したのか? GitHub 上の既存の RPG Maker MZ MCP サーバーには深刻な問題があります — stdout 汚染による MCP プロトコル破損、間違ったファイル拡張子、アトミック書き込みなし、テストなし、古い SDK。本プロジェクトはこれらすべてをゼロから解決しました。
特徴
アトミック書き込み:
.tmp一時ファイルに書き込み →fs.rename()で上書き。書き込み途中のデータ破損を防止自動バックアップ:書き込み前に自動で
.bakバックアップを作成Zod バリデーション:JSON 読み取り時に Zod スキーマで検証。安全でない
as T型アサーションを排除汎用データベースマネージャー:
DatabaseManager<T>一つで全 8 種のエンティティの CRUD を処理。コードの重複を排除stderr 専用ログ:MCP は stdout を JSON-RPC 通信に使用。
console.logはプロトコルを破壊するため、console.errorのみ使用バージョン同期:データファイル変更のたびに
System.jsonのversionIdを自動更新し、RPGツクールMZ エディタに再読み込みを強制
利用可能なツール(全 23 個)
カテゴリ | ツール数 | 説明 |
プロジェクト管理 | 4 | 読み込み / 作成 / 情報取得 / リソース一覧 |
データベース CRUD | 6 | 一覧 / 取得 / 作成 / 更新 / 削除 / 検索(アクター、職業、スキル、アイテム、武器、防具、敵キャラ、ステート対応) |
マップ管理 | 5 | 一覧 / 作成 / 詳細 / 更新 / 削除 |
イベント編集 | 5 | 一覧 / 作成 / 更新 / コマンド追加 / 削除(40以上の人間が読めるコマンド形式対応) |
AI シナリオ生成 | 3 | ゲームシナリオ概要 / NPC 会話 / クエスト設計の生成 |
使用例
MCP サーバー接続後、Claude に自然言語で話しかけるだけで操作できます:
あなた:/Users/me/Games/MyRPG にある RPGツクールMZ のプロジェクトを読み込んで
あなた:「ローランド」という名前の戦士キャラクターを作って、攻撃力を高めに
あなた:20x15 の村マップを作って、名前は「オークウッド村」、BGMは Town1 で
あなた:マップ 2 の座標 (8, 6) に NPC の商人を配置して
あなた:商人にセリフを追加して:「いらっしゃいませ!商品をご覧ください。」
あなた:さらわれた姫を救出するクエストを設計して
あなた:HP を 200 回復する回復薬を作ってインストールと設定
git clone https://github.com/a951753abc/rpgmaker-mz-mcp.git
cd rpgmaker-mz-mcp
npm install
npm run build
npm test # 42 テストがすべてパスするはずプロジェクトディレクトリに .mcp.json を作成:
{
"mcpServers": {
"rpgmaker-mz": {
"command": "node",
"args": ["/path/to/rpgmaker-mz-mcp/dist/index.js"]
}
}
}Available Tools
23 toolsadd_event_commandsA
Add commands to an event page. Commands use human-readable format that gets converted to RPG Maker MZ codes.
Supported command types:
show_text: { type: "show_text", face: "Actor1", faceIndex: 0, text: "Hello!" }
show_choices: { type: "show_choices", choices: ["Yes", "No"] }
transfer_player: { type: "transfer_player", mapId: 1, x: 5, y: 5 }
control_switches: { type: "control_switches", startId: 1, value: 0 } (0=ON, 1=OFF)
control_variables: { type: "control_variables", startId: 1, operationType: 0, operand: 0, value: 100 }
control_self_switch: { type: "control_self_switch", key: "A", value: 0 }
conditional_branch: { type: "conditional_branch", conditionType: 0, param1: 1, param2: 0 }
common_event: { type: "common_event", eventId: 1 }
change_gold: { type: "change_gold", operation: 0, value: 100 }
change_items: { type: "change_items", itemId: 1, operation: 0, value: 1 }
play_bgm: { type: "play_bgm", name: "Town1", volume: 90 }
play_se: { type: "play_se", name: "Decision1" }
wait: { type: "wait", duration: 60 }
fadeout_screen, fadein_screen, erase_event, game_over, return_to_title
comment: { type: "comment", text: "This is a comment" }
label/jump_to_label: { type: "label", name: "start" }
And many more (change_hp, change_exp, battle_processing, shop_processing, etc.)
| Name | Required | Description | Default |
|---|---|---|---|
| mapId | Yes | Map ID | |
| append | No | If true, append to existing commands. If false, replace all commands. | |
| eventId | Yes | Event ID | |
| commands | Yes | Array of command objects with "type" field | |
| pageIndex | No | Page index (0-based) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It does disclose a genuinely useful trait: commands are authored in a human-readable form that 'gets converted to RPG Maker MZ codes.' However, it says nothing about mutation risk, whether append=false silently destroys existing page commands, whether indices shift, persistence, or failure modes.
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?
Purpose is front-loaded in the first sentence, and the long bullet block is reference material where each line earns its place by naming a command type and its payload shape. Slightly long, and the trailing 'And many more' is a mild hedge, but the structure is scannable.
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 tool whose core parameter is a polymorphic array of objects, the supported-type catalogue is exactly the missing documentation and it is supplied. The remaining gaps (append semantics, pageIndex behavior, how to discover unlisted command types) are covered by the schema or are minor. No output schema exists, so no return-value explanation is owed.
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 coverage is 100%, so the baseline would be 3, but the description goes well beyond the schema by decoding the free-form `commands` array: it enumerates concrete command types with example payloads and field names (show_text, control_switches, change_gold, etc.). That is precisely the meaning an agent could not infer from 'Array of command objects with "type" field.'
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 first sentence gives a specific verb and resource: 'Add commands to an event page.' It is instantly clear this mutates event-page command lists rather than creating/updating the event itself. It does not, however, explicitly contrast itself with siblings like update_event or create_event, which an agent may also consider.
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 never states when to reach for this tool versus create_event/update_event, nor any prerequisites (e.g., a loaded project, an existing page). The only usage-relevant signal is the implicit 'add commands' framing. The append-vs-replace decision, which is central to correct use, is left entirely to the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_entityB
Create a new entity. Provide the entity data as a JSON object. Required: name. Other fields use defaults if omitted.
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | Entity data (JSON object). Must include "name". | |
| entityType | Yes | Entity type to create |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure for a mutation tool. It mentions that omitted fields default, which is useful, but omits critical traits such as permissions required, whether the operation is idempotent, what happens on duplicate names, and what the tool returns.
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?
Three short sentences, front-loaded with the core action, then required parameter info, then a default-behavior note. Every sentence contributes and nothing is wasted.
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 create tool with a nested free-form data object, an enum-driven entityType, no output schema, and no annotations, the description is minimally adequate. It states the required field and default behavior but leaves out return format, error behavior, and how entityType constrains the shape of data.
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 100%, so the schema already documents both parameters thoroughly. The description adds a small amount of meaning by noting that only 'name' is required within data and that other fields default, but it does not explain the entityType-specific structure of the data object.
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 clearly states a specific verb and resource: 'Create a new entity.' However, it does not differentiate this tool from its many siblings like create_event, create_map, or create_project, so an agent must rely on the name alone to disambiguate.
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 is implied by the tool name and the instruction to provide entity data, but there is no explicit when-to-use guidance, no mention of when not to use it, and no reference to alternatives such as update_entity or get_entity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_eventC
Create a new event on a map at the specified position.
| Name | Required | Description | Default |
|---|---|---|---|
| x | Yes | X position on map | |
| y | Yes | Y position on map | |
| name | Yes | Event name | |
| note | No | Event note | |
| mapId | Yes | Map ID | |
| trigger | No | Trigger: 0=Action Button, 1=Player Touch, 2=Event Touch, 3=Autorun, 4=Parallel | |
| characterName | No | Character sprite name | |
| characterIndex | No | Character sprite index |
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 says nothing about what happens on success (returned ID?), permission requirements, default trigger behavior, or whether the created event is immediately active or enabled, which matters for a mutation 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?
A single front-loaded sentence with no filler; the action and location constraint come first. It is efficient, though minimal enough that no additional structure or emphasis is present.
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?
With a fully documented 8-parameter schema and no output schema, the main remaining burden is behavioral and usage context, which the description does not supply. It is adequate to identify the operation but incomplete for a mutation tool with zero annotation coverage.
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 100%, including a documented trigger enum mapping (0=Action Button ... 4=Parallel) and coordinate constraints, so the schema does the heavy lifting. The description only echoes position and map, adding no meaning beyond what the schema already states; baseline 3 is appropriate.
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 gives a specific verb and resource ('Create a new event') plus its scope ('on a map at the specified position'), so the agent knows exactly what operation is performed. It does not, however, distinguish this from siblings like add_event_commands or update_event, leaving the boundary between creation and modification implicit.
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 when-to-use guidance, no prerequisites, and no mention of alternatives such as add_event_commands for populating an existing event or update_event for changing one. The agent must infer usage purely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_mapC
Create a new map.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Map name | |
| width | No | Map width in tiles | |
| height | No | Map height in tiles | |
| bgmName | No | Background music name | |
| parentId | No | Parent map ID (0 for root) | |
| tilesetId | No | Tileset ID to use |
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, and it delivers almost nothing. It doesn't state side effects, whether an ID is returned, whether the map is immediately active, or permission requirements. For a mutation tool with zero annotation coverage, this is a serious gap.
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 short sentence with no filler. It is front-loaded and efficient, though that brevity is the result of underspecification rather than deliberate compression.
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 6-parameter mutation tool with no annotations and no output schema, the description is far too thin. It omits creation context (project dependency), parent map hierarchy implications, and return behavior, leaving the agent to infer almost everything from the schema alone.
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 100%, so the schema already documents all six parameters including defaults, ranges, and meanings. The description adds no parameter information beyond what the schema provides, which is the baseline 3 when schema does the heavy lifting.
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 'Create a new map' restates the tool name with no added specificity. It doesn't distinguish from sibling update_map or get_map beyond the implied create vs read/update verb, but offers no scope, domain, or product context (e.g., RPG Maker-style map). This is essentially a tautology against the name.
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?
No guidance on when to use this versus alternatives, no prerequisites stated (e.g., whether a project must be loaded first, which load_project and create_project siblings suggest), and no mention of required name uniqueness or parent map relationships. The agent gets no routing information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_projectA
Create a new RPG Maker MZ project with default data files.
| Name | Required | Description | Default |
|---|---|---|---|
| gameTitle | Yes | Title of the game | |
| projectPath | Yes | Absolute path where the project will be created | |
| rpgmakerPath | No | RPG Maker MZ installation path (auto-detected if omitted) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully disclose behavioral traits. It states that the tool creates a project with default data files, but does not clarify whether the operation is idempotent, what happens if a project already exists at the given path, whether it requires specific permissions, or what the return value indicates. For a creation tool, this is a significant gap.
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 that is front-loaded with the core action. There is no unnecessary information, making it efficient and easy to parse.
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?
Given the complexity of project creation, the description is minimally adequate. It lacks details about error conditions, side effects, and expected outcomes. No output schema exists, so the description should explain return values or success indicators, which it does not.
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 100%, so the input schema already documents all three parameters with clear descriptions. The tool description adds no additional parameter-level detail beyond what is in the schema, so the baseline of 3 is appropriate.
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 clearly states a specific action ('Create') and resource ('RPG Maker MZ project') along with an additional detail ('with default data files'). This distinguishes it from sibling tools like 'create_map' or 'create_entity' which create different resources within a project.
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 usage by describing what the tool does, but provides no explicit guidance on when to use this specific tool versus alternatives like 'load_project' or 'get_project_info'. It does not state prerequisites such as needing a valid project path or a compatible RPG Maker MZ installation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
delete_entityA
Delete an entity by ID. Cannot delete system default entities (ID 1) for actors/classes/states.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Entity ID to delete | |
| entityType | Yes | Entity type |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose an important guardrail: system default entities (ID 1) for actors/classes/states are protected. However, it is silent on whether deletion is permanent, whether it cascades to references (maps, events, quests), and what authorization is required for a destructive operation.
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?
Two short sentences, zero filler, with the core action stated first and the guardrail second. Every sentence 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 destructive two-parameter tool with no annotations and no output schema, the description covers the action and one critical constraint, but omits permanence, side effects on related data, and the success/failure response shape an agent would want before invoking a delete.
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 100%, so both parameters are already documented in the schema, establishing the baseline of 3. The description's mention of ID 1 protection adds a small amount of meaning about valid id values but nothing about the entityType enum behavior.
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 (delete) and resource (entity), and the 'by ID' phrasing matches the required id parameter. It distinguishes itself from sibling deletions such as delete_map and delete_event, though it never names the alternative tools explicitly.
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?
It implies usage through the destructive verb and gives one concrete constraint (system default entities with ID 1 cannot be deleted), but provides no when-to-use guidance, no routing to get_entity/update_entity for non-deletion needs, and no prerequisites or permissions context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
delete_eventC
Delete an event from a map.
| Name | Required | Description | Default |
|---|---|---|---|
| mapId | Yes | Map ID | |
| eventId | Yes | Event ID to delete |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral burden, but it only says 'Delete an event from a map.' It omits critical details such as irreversibility, required permissions, or side effects. This is minimal disclosure for a destructive operation.
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 front-loaded sentence with no wasted words. It is appropriately sized for a simple tool, though its brevity borders on under-specification rather than pure conciseness.
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 deletion tool with no annotations and no output schema, the description should provide at least some behavioral or usage context. It does not, leaving important gaps around reversibility, permissions, and expected outcomes.
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 100%, so the schema already documents both parameters (mapId, eventId) fully. The description adds no parameter-level meaning, which matches the baseline of 3 when the schema does the heavy lifting.
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 ('Delete') and resource ('an event from a map'), making the tool's function immediately clear. It does not, however, differentiate from sibling tools like update_event or delete_map, which would be required for a 5.
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, no prerequisites, and no exclusions. The description only states what it does, leaving all context to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
delete_mapB
Delete a map. Cannot delete Map 1 (system default).
| Name | Required | Description | Default |
|---|---|---|---|
| mapId | Yes | Map ID to delete |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses a real behavioral guardrail -- Map 1 (system default) cannot be deleted -- but omits whether deletion is permanent/irreversible, what happens to entities referencing the map, and any permission requirements.
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?
Two short sentences with zero waste; the one behavioral constraint is front-loaded immediately after the purpose statement.
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 destructive single-parameter tool with no annotations and no output schema, the description covers the essential default-map safeguard but leaves irreversibility and side effects unstated. Adequate but with a clear gap.
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 100%, so mapId and its constraint (exclusiveMinimum 0) are already documented in the schema. The description adds no syntax or format detail beyond that, so baseline 3 applies.
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 (Delete) and resource (map), matching the create_map/get_map/update_map/list_maps CRUD family. It does not explicitly name sibling tools to differentiate itself, but the action is unambiguous.
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 gives no when-to-use guidance, no prerequisites, and no alternatives (there is no restore/undelete sibling mentioned). The Map 1 restriction is a hard constraint, not usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
generate_dialogueA
Generate NPC dialogue for a scene. Returns event commands that can be directly used with add_event_commands.
| Name | Required | Description | Default |
|---|---|---|---|
| mood | No | friendly | |
| scene | Yes | Scene description (e.g., "NPC in weapon shop greets the hero") | |
| npcName | Yes | NPC name | |
| faceName | No | Face image filename (e.g., "Actor1") | |
| faceIndex | No | Face image index | |
| lineCount | No | Number of dialogue lines |
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. It does disclose a key behavioral trait: the return value is event commands directly consumable by add_event_commands. However, it does not say whether generation is deterministic, whether it writes to the project or is pure, what happens with invalid mood/large lineCount, or any auth/permission requirements.
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?
Two sentences, zero filler, with the core purpose front-loaded and the integration detail second. Nothing to trim and nothing placed after the point where it matters.
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 6-parameter generative tool with no annotations and no output schema, the description is only minimally sufficient. It hints at the return shape ('event commands') but not their structure, so an agent must call add_event_commands or inspect the output to know what it receives.
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 83%, so the schema already documents scene, npcName, faceName, faceIndex, and lineCount. The description adds no parameter-level detail and says nothing about the mood enum or the 1-10 lineCount bounds. Baseline 3 applies when the schema does the heavy lifting.
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?
Specific verb + resource ('Generate NPC dialogue for a scene') with a clear scope, and it distinguishes itself from the sibling add_event_commands by naming that tool as the downstream consumer of its output rather than an alternative. An agent can tell what this tool produces without opening the schema.
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 workflow (its output feeds add_event_commands) but gives no explicit when-to-use guidance, no conditions that select it over siblings like generate_scenario or create_event, and no exclusions or prerequisites. Usage is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
generate_questC
Generate a quest design with objectives, rewards, and event flow.
| Name | Required | Description | Default |
|---|---|---|---|
| questType | Yes | Quest type | |
| difficulty | No | normal | |
| rewardType | No | mixed | |
| description | Yes | Quest description or theme |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full behavioral burden, but it does not. It mentions the generated components, yet says nothing about persistence, permissions, determinism, side effects, or how this relates to sibling tools that create events or entities.
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, front-loaded sentence with no filler or redundancy. It is appropriately sized for its content.
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 generator tool with four parameters, no output schema, and no annotations, the description is too thin. It omits output structure, side effects, and how it fits with sibling generation tools, leaving an agent without enough context to call it confidently.
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 50%, and the description does little to compensate. It does not explain the meaning or effect of questType, difficulty, or rewardType parameters; 'rewards' only loosely hints at rewardType, leaving the other two undocumented beyond their enum values.
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 gives a specific verb+resource ('Generate a quest design') and names the generated components ('objectives, rewards, and event flow'). It is clear what the tool does, but it does not distinguish itself from siblings like generate_scenario or generate_dialogue.
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 generate_scenario or generate_dialogue. The description only states what it does, not the context or prerequisites for invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
generate_scenarioA
Generate a game scenario outline based on theme and genre. Returns structured suggestions that can be implemented using other tools (create_entity, create_map, create_event, etc.).
| Name | Required | Description | Default |
|---|---|---|---|
| genre | No | Game genre | RPG |
| scope | No | Scope: small (3-5 maps, 2-3 characters), medium (8-12 maps, 5-8 characters), large (15+ maps, 10+ characters) | medium |
| theme | Yes | Game theme or premise (e.g., "medieval fantasy adventure") |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. Stating that it returns 'structured suggestions' implies the operation is non-persistent, which is useful, but it does not clarify whether anything is written to the project, whether it requires an open/loaded project, or any limits.
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?
Two sentences, zero waste, purpose front-loaded before the downstream-tool hint. Every clause 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 3-parameter generator with no output schema and no annotations, the description should say more about the returned structure and whether project state is touched. It covers the purpose and downstream usage but leaves the output/persistence question open.
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 100%, and the scope enum is fully documented in the schema, so the baseline is 3. The description adds only that theme and genre drive generation, adding little 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 states a specific verb and resource ('Generate a game scenario outline') and names the inputs (theme, genre). It is clearly different from create_entity or create_map, though it does not distinguish itself from the similar generator siblings generate_quest and generate_dialogue.
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?
It implies usage by noting the output 'can be implemented using other tools (create_entity, create_map, create_event)'. This gives a workflow hint but no explicit when-to-use or when-not-to-use guidance relative to generate_quest or generate_dialogue.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_entityB
Get detailed information about a specific entity by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Entity ID | |
| entityType | Yes | Entity type |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It does not state that this is a read-only operation, what happens when the ID does not exist, whether any permissions are required, or what 'detailed information' comprises.
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 with no redundant or filler content. It is tight, though arguably under-informative rather than optimally economical.
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 two-parameter read tool with full schema coverage and no output schema, the essentials are present. Still missing error/missing-entity behavior and any hint about the shape or scope of the returned detail.
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 100%, so both parameters (id, entityType) and the enum of entity types are already documented in the schema. The description only restates the ID lookup, adding no syntax or format detail beyond what the schema provides.
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 (get) and resource (entity) plus the retrieval key (by ID), which distinguishes it from search_entities and list_entities. However, it never names those siblings explicitly, so the differentiation must be inferred.
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 'by ID' implicitly signals the precondition (use when you already have an ID), but there is no explicit when-to-use/when-not guidance and no reference to search_entities or list_entities as alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_mapB
Get detailed information about a specific map, including its events.
| Name | Required | Description | Default |
|---|---|---|---|
| mapId | Yes | Map ID |
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. The verb 'Get' implies read-only behavior and 'including its events' discloses return content, but no permissions, rate limits, error behavior, or explicit safety profile are described. For a simple getter this is minimally adequate, but gaps remain.
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?
Single sentence, front-loaded with the action and scope. There is no filler; every word contributes to the stated purpose.
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 with one required parameter and no output schema. The description gives a rough return scope ('detailed information ... including its events') but no field-level detail, and it does not cover prerequisites such as needing list_maps to find a mapId. Adequate but not thorough.
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 100% and the single parameter mapId is documented in the schema as 'Map ID'. The description adds no syntax or format detail beyond 'specific map', so the baseline of 3 is appropriate.
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 'Get' and resource 'map', and scopes to 'a specific map' versus sibling list_maps; 'including its events' clarifies returned content. It does not explicitly name alternatives, but sufficiently distinguishes itself from list/create/update/delete map siblings.
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?
No when-to-use guidance, no mention of alternatives like list_maps for obtaining a mapId or get_entity when entity details are needed. Usage is only implied by the phrase 'specific map'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_project_infoA
Get information about the currently loaded RPG Maker MZ project.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. The verb 'Get' plus the read-only nature of a 0-param info getter makes the safety profile obvious, and 'currently loaded' is a meaningful behavioral qualifier. It still does not say what happens if no project is loaded and discloses nothing about the returned data.
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 with no filler. Nothing is repeated and nothing wastes the agent's attention.
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 0-param reader this is close to adequate, but with no output schema and no annotations, the description never hints at what fields the 'information' contains (project name, path, version, etc.) or the failure mode when nothing is loaded. Those are the remaining gaps for an otherwise complete definition.
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?
The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No parameter-related information is missing.
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 ('Get') and resource ('information about the currently loaded RPG Maker MZ project'), which is concrete and unambiguous. It does not, however, differentiate itself from siblings like list_resources or list_entities, which also surface project-derived data.
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 'currently loaded' implies the prerequisite that a project must first be loaded (presumably via load_project), which is useful implicit guidance. Beyond that, there is no explicit when-to-use vs. when-not guidance or named alternative, so usage is only inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_entitiesC
List all entities of a given type (actors, items, weapons, etc.)
| Name | Required | Description | Default |
|---|---|---|---|
| entityType | Yes | Entity type to list |
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 implies a read-only, unfiltered enumeration via 'list all', but discloses nothing about pagination, result format, size limits, or whether full entity objects or summaries are returned.
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 with zero filler. It is efficient, though the brevity contributes to the missing behavioral detail rather than being deliberately dense.
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 one-parameter list tool the definition is enough to invoke, but with no output schema and no annotations it should still say something about return shape or result size. Adequate but with a clear gap.
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 100% and the enum fully documents the valid types. The parenthetical examples in the description largely restate the enum rather than adding format or semantics beyond what the schema already provides, so the baseline 3 applies.
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 (List) and resource (entities) with a clear scope qualifier ('of a given type') plus concrete examples. It is distinguishable from get_entity (single) and search_entities (filtered), though it never explicitly names those siblings.
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 gives no when-to-use vs alternatives guidance, even though siblings like search_entities and get_entity overlap in purpose. The 'list all' phrasing implies bulk retrieval but there is no explicit condition or exclusion to steer the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_eventsC
List all events on a specific map.
| Name | Required | Description | Default |
|---|---|---|---|
| mapId | Yes | Map ID |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the full burden. It does not state whether events are returned in a specific order, whether they are filtered, pagination behavior, or response shape. For a list tool with no annotations and no output schema, more behavioral context is warranted.
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?
Single efficient sentence that front-loads the action and resource. No wasted words, though it is perhaps too terse given the lack of behavioral detail.
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?
Adequate for a simple list tool with one parameter, but missing details like whether events are scoped to the map, return ordering, or any auth/permission requirements. With no annotations and no output schema, more context would improve it.
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 coverage is 100%, so the schema already documents the mapId parameter. The description adds no syntax or format details beyond what the schema provides. Baseline 3 is appropriate.
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?
Clear verb (List) and resource (events) with scope (on a specific map). Distinguishes from create_event, update_event, delete_event, add_event_commands, but does not distinguish from other list_* siblings like list_maps or list_entities.
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?
No guidance on when to use this versus alternatives, no prerequisites, no exclusions. Implied usage only.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_mapsB
List all maps in the project with their hierarchy.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations and no output schema, the description carries the full behavioral burden, yet it only hints that results include hierarchy. Nothing is said about pagination, ordering, permissions, or result size for a tool that enumerates everything in the project.
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 with no filler. The scope qualifier ('in the project') and the return hint ('with their hierarchy') are both packed in without waste.
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 zero-parameter read tool this covers the basics: what it returns and where it looks. Still missing are the shape of the returned hierarchy, ordering, and any auth or pagination expectations that an agent would need before relying on the output.
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?
The tool takes zero parameters, so there is no parameter surface for the description to clarify; baseline 4 applies. Schema coverage is 100% trivially.
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 (List) and resource (maps) plus scope ('in the project'), so the operation is unambiguous. However, it does not differentiate itself from siblings like get_map or the other list_* tools, leaving the agent to infer the distinction from the name alone.
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?
Listing usage is implied by the verb and the 'in the project' scope, but the description never states when to prefer this over get_map (single map) or list_entities/list_resources. No exclusions or prerequisites are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_resourcesC
List resource files (images, audio) in the project.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Filter by type: "img" or "audio" |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It implies a read-only listing but says nothing about permissions, whether results are scoped to the loaded project, ordering, or pagination. For a zero-annotation tool this is a notable gap.
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 short, front-loaded sentence with no wasted words. It is efficient, though the brevity contributes to the transparency gaps noted elsewhere.
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 one-optional-parameter list tool with no output schema and no annotations, the description is minimally viable but leaves return content, ordering, and project scoping unspecified. An agent could call it, but not confidently predict the result.
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 100% and the single 'type' parameter is already documented with its allowed values ("img" or "audio") in the schema. The description adds only the general idea of filtering by resource kind, which the schema already conveys, so baseline 3 applies.
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 (List) and resource (resource files in the project), plus parenthetical examples of what those are (images, audio). It does not name or distinguish itself from any sibling, but the resource noun is concrete enough that an agent can place it.
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 versus list_entities, list_maps, or other listing tools, and no mention of prerequisites such as whether a project must first be loaded. Usage is only inferable from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
load_projectA
Load an existing RPG Maker MZ project. Must be called before using other tools.
| Name | Required | Description | Default |
|---|---|---|---|
| projectPath | Yes | Absolute path to the RPG Maker MZ project directory |
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 clearly communicates a state-changing, prerequisite nature by stating it must be called before other tools. However, it does not disclose whether it fails on invalid paths, whether it returns project data, or any side effects.
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?
Two short sentences with zero waste. The prerequisite requirement is front-loaded after the purpose, making it easy to scan and understand.
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 single-parameter initialization tool with no output schema and no annotations, the description provides everything needed: what it does and that it must be called first. No significant gaps remain.
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?
The schema already provides a complete description for projectPath ('Absolute path to the RPG Maker MZ project directory') at 100% coverage. The description adds no further parameter meaning beyond what the schema provides, so a baseline 3 is appropriate.
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: 'Load an existing RPG Maker MZ project.' This distinguishes it from creation (create_project) and read-only tools. However, it does not explicitly differentiate itself from sibling tools like get_project_info or list_resources, which also operate on projects.
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?
Explicitly states 'Must be called before using other tools.' This provides unambiguous when-to-use guidance and establishes the tool as a prerequisite, which is critical for correct invocation order.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_entitiesC
Search entities by keyword across name and description fields.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search keyword | |
| entityType | Yes | Entity type to search |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden but provides almost no behavioral disclosure. It says the search matches name and description fields, but does not indicate whether the operation is read-only, what permissions are required, whether results are paginated or limited, or how matching works (case sensitivity, partial matches, etc.).
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 with no redundancy, front-loading the core action and scope. 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 tool with two required parameters (including an enum) and no output schema, the description is too sparse. It omits the required entityType scoping, gives no indication of return format or result limits, and contains no usage guidance relative to sibling tools, leaving significant gaps for an 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 100%, so the baseline is 3. The description adds that the query searches across name and description fields, which is slight extra context, but it says nothing about the required entityType parameter or any other semantics beyond what the schema already provides.
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 (Search) and resource (entities) with the scope 'across name and description fields'. However, it fails to mention the required entityType parameter, leaving it unclear whether the search is scoped to a particular entity type, and does not explicitly distinguish itself from siblings like list_entities or get_entity.
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?
No guidance is given on when to use this tool versus alternatives like list_entities, get_entity, or any other search mechanism. The description only states what it does, not the context or conditions for choosing it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
update_entityB
Update an existing entity. Only provided fields will be changed.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Entity ID to update | |
| data | Yes | Fields to update (JSON object) | |
| entityType | Yes | Entity type |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does disclose one genuinely useful behavioral trait — merge/PATCH semantics ('only provided fields will be changed') — but says nothing about permissions, whether entityType must match the stored entity, error behavior on unknown fields, or reversibility.
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?
Two short sentences, zero waste, with the action stated first and the partial-update constraint front-loaded immediately after. Nothing is padded or restated.
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?
This is a mutation tool with no annotations and no output schema, and its 'data' parameter accepts an arbitrary nested object whose valid fields are entity-type dependent. The description should cover permissions, the meaning of entityType relative to the target, and the response shape, but covers none of them.
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 coverage is 100%, so all three parameters are already documented in the schema, and the description adds no syntax or format detail. The free-form nested 'data' object whose valid keys depend on entityType is the main semantic gap, but with full schema coverage the baseline of 3 applies.
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 (update) plus resource (entity) and adds the partial-update scope. The resource name distinguishes it from sibling mutators like update_map and update_event, but it never explicitly contrasts itself with create_entity/delete_entity, so it falls short of the 5 bar.
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?
No when-to-use guidance, no prerequisites, no alternatives named. The reader must infer from the sibling list that create_entity and delete_entity cover the other cases; the description itself offers no routing context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
update_eventC
Update event properties (name, position, note, character sprite).
| Name | Required | Description | Default |
|---|---|---|---|
| x | No | New X position | |
| y | No | New Y position | |
| name | No | New event name | |
| note | No | New event note | |
| mapId | Yes | Map ID | |
| eventId | Yes | Event ID | |
| characterName | No | Character sprite name (applies to page 1) | |
| characterIndex | No | Character sprite index (applies to page 1) |
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. It says 'update' (implying mutation) but does not state whether changes are reversible, whether partial updates are allowed, permissions required, or what happens to omitted fields. It also mentions character sprite applies to page 1, a small useful detail, but overall behavioral disclosure is thin.
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 efficient sentence that front-loads the verb and resource. No wasted words, though the parenthetical grouping of properties is somewhat vague about which parameters are actually available.
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?
Eight parameters, no annotations, and no output schema. The description does not mention required mapId/eventId, does not explain the page-1 restriction mentioned only for character fields, and does not cover partial update semantics. For an 8-parameter mutation tool, this is insufficient.
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 100%, so the schema already documents all 8 parameters with clear descriptions. The description lists four property categories but adds no syntax, format, or constraint details beyond what the schema provides. Baseline is 3 for high coverage; here the description repeats schema content and even omits that x/y are separate from 'position' and that characterName/characterIndex are distinct, so it is slightly less useful than the schema alone.
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 (update) and resource (event) plus the properties affected (name, position, note, character sprite), which is more detail than the bare title. However, it does not distinguish this from siblings like update_entity or update_map, leaving some ambiguity about scope when multiple update tools exist.
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?
No guidance on when to use this versus create_event, delete_event, or other update tools. The description gives no prerequisites, no indication of when not to use it, and no mention of alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
update_mapC
Update map properties (name, display name, BGM, note, etc.).
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | New map name (in MapInfos) | |
| note | No | Map note | |
| mapId | Yes | Map ID | |
| bgmName | No | BGM name (empty string to disable) | |
| bgsName | No | BGS name (empty string to disable) | |
| tilesetId | No | New tileset ID | |
| displayName | No | Display name shown in-game | |
| disableDashing | No | Disable dashing on this map |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It never states whether this is a partial update (unspecified fields preserved) or a full overwrite, what happens to a nonexistent mapId, or whether permissions are required. For a mutation tool with zero annotation coverage, this is a significant gap.
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 compact sentence with the action verb front-loaded and no filler. It is efficient, though the trailing 'etc.' adds no information and slightly weakens precision.
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 an unannotated 8-parameter mutation tool with no output schema, the description omits what an agent most needs: partial-update semantics, failure behavior, and any required permissions or preconditions. The schema covers field-level detail, but the behavioral contract is absent.
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 100%, so every parameter (name, note, bgmName, bgsName, tilesetId, displayName, disableDashing, mapId) is already documented in the schema. The description recites a subset of these plus a vague 'etc.', adding no semantics beyond the structured fields. Baseline 3 applies.
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 and resource ('Update map properties') and enumerates representative fields, so an agent knows this mutates an existing map. It does not distinguish itself from potential overlapping siblings, but none of the sibling names (update_event, update_entity) collide with maps.
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 contains no when-to-use guidance, no prerequisites (e.g. needing mapId to exist), and no pointer to alternatives for related operations like create_map or delete_map. Usage is only implied by the word 'Update'.
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.
23 tool updates
v1.0.0- First observed
add_event_commands - First observed
create_entity - First observed
create_event - First observed
create_map - First observed
create_project - First observed
delete_entity - First observed
delete_event - First observed
delete_map - First observed
generate_dialogue - First observed
generate_quest - First observed
generate_scenario - First observed
get_entity - First observed
get_map - First observed
get_project_info - First observed
list_entities - First observed
list_events - First observed
list_maps - First observed
list_resources - First observed
load_project - First observed
search_entities - First observed
update_entity - First observed
update_event - First observed
update_map
TDQS
Scored across 23 tools
Most tools have clearly distinct purposes, cleanly separated by resource (entities, maps, events) and action (list/get/create/update/delete). The only mild overlap is among the generation tools (generate_quest, generate_scenario, generate_dialogue), which are related but target different scopes (quest vs. full scenario vs. dialogue), and add_event_commands vs. generate_dialogue which is complementary rather than conflicting.
Nearly every tool follows a strict verb_noun snake_case pattern (get_project_info, load_project, create_entity, update_map, delete_event, add_event_commands). The convention is applied uniformly across projects, resources, entities, maps, and events with no style mixing.
23 tools sits at the heavy end of the reasonable range, but the domain genuinely spans projects, resources, entities, maps, events, event commands, and content generators, so most tools earn their place. Slightly more than ideal, but not bloated or redundant.
The surface covers the full lifecycle well: project load/create/info, entity and map and event CRUD, and rich event-command authoring plus generators. Minor gaps exist (e.g. no get_event for a single event, no way to remove/edit already-added event commands, no delete_project), but agents can work around these.
Maintenance
Related MCP Connectors
An MCP server that integrates with Discord to provide AI-powered features.
MCP server for AI dialogue using various LLM models via AceDataCloud
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
MCP server for NanoBanana AI image generation and editing
Related MCP Servers
- FlicenseCqualityDmaintenanceA Model Context Protocol server that enables management of RPG Maker MZ and MV project data, including actors, items, maps, and events. It allows users to create, update, and search game assets through natural language integration with MCP-compatible clients.371-
- AlicenseAqualityDmaintenanceAn MCP server that gives AI assistants direct control over Godot 4 game development projects. It enables launching the editor, running projects, creating and editing scenes, writing GDScript, and inspecting assets through natural language commands.4410 npm4MIT
- AlicenseNot gradedqualityBmaintenanceA plugin-based MCP server that enables AI assistants to interact with external systems through custom tools, resources, and prompts.4AGPL 3.0
- AlicenseNot gradedqualityCmaintenanceAn MCP server that enables AI agents to act as dynamic dungeon masters for text-based RPGs with dynamically generated rule systems and comprehensive game state management.11 npm10MIT