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., "@WorldPainter MCP 读取 D:\Maps\island.world，生成地形与植被编辑预览，并另存为新副本"
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.
通过 MCP 读取已保存的 .world 工程，生成润色计划、预览，再调用 WorldPainter 自带的 wpscript.exe 保存新副本。
它操作工程文件。要在 WorldPainter 窗口里看到修改，需要打开新副本；未保存的窗口状态无法读取。
环境：Windows、Python 3.11 或以上、WorldPainter。实际验证环境为 WorldPainter 2.27.1 / Java 22 / Python 3.14。 观众需要自行安装 WorldPainter 与 Python，压缩包包含本工具源码，不包含 WorldPainter、Python 或地图数据。
从 GitHub Releases 下载版本包，或使用仓库的 Code → Download ZIP 下载源码。解压到一个固定目录，例如 D:\Tools\worldpainter-mcp。
在该目录打开 PowerShell：
Set-ExecutionPolicy -Scope Process Bypass
.\scripts\install.ps1 -WPScript 'D:\WorldPainter\wpscript.exe'将 wpscript.exe 的路径改为自己电脑上的实际路径。-Python 参数可以指定 Python 可执行文件，默认使用 Windows 的 py 启动器。
首次安装会联网下载 Python 依赖。后续读写地图通过本机 WorldPainter 进程执行。
在 MCP 客户端添加 STDIO 服务：
项目 | 示例 |
命令 |
|
参数 |
|
工作目录 |
|
环境变量 |
|
工具超时 | 900 秒 |
Codex 与 Hermes 配置示例位于 examples/，请替换绝对路径。更新旧版本后重启 MCP 客户端，让 Python 服务重新加载。
Related MCP server: armorpaint-mcp
先在 WorldPainter 保存工程，再交给助手：
请读取 D:\Maps\island.world，分析地形和海岸。按高度与坡度规划草地、裸岩、海岸以及 Minecraft 群系，创建草类植物图层。先生成预览，再把合理的方案另存为新的 .world 工程。
工具调用顺序：
wp_get_world_info：核实文件、维度、范围和图层。
wp_analyze_terrain：读取高度与坡度摘要。
wp_plan_terrain_edit：生成计划，不保存地图。
wp_preview_terrain_edit：生成高度前后对比、改变量与每项覆盖遮罩，返回 preview_id。
审阅预览后调用 wp_apply_terrain_plan：自动保存源文件快照，默认另存工程副本。
重新读取新副本，核实图层；在 WorldPainter 打开副本查看效果。
原文件、输入遮罩或编译后的覆盖数据在预览后变化，应用会被拒绝。默认最多处理一亿格点，8192×8192 地图约为 6711 万格点。
高度操作：平滑、局部抬高/降低、坡度限制、海岸柔化、山脊/谷地对比和侵蚀感处理。侵蚀感算法为视觉处理，不是水文模拟。
绘制操作：内置地表材质、已有图层数值、Minecraft 群系 ID、新建原生 Custom Plants 图层，以及按准备好的格点数据写入湖泊与河道床面、水位。
矩形、圆形、多边形可限定区域。灰度遮罩必须与整张维度同尺寸，左上角对应该维度最小坐标。
每项绘制可以单独指定 mask_path，它与全局遮罩相交。
植物示例，放入 paint_operations：
{
"type": "plants",
"layer": "Island | Low grass",
"plants": [
{"name": "Short Grass", "weight": 94},
{"name": "Tall Grass", "weight": 4},
{"name": "Dandelion", "weight": 2}
],
"density": 0.30,
"seed": 20261003,
"mask_path": "D:\\Maps\\grass-mask.png"
}density 为适宜区域中的覆盖比例，0～1；weight 为植物类型的相对权重。
植物使用 WorldPainter 的英文名称，图层名必须是新名字，避免替换已有图层配置。
覆盖位置由固定种子生成，原生 Plants 图层为开关型图层。植物只在有效基础方块上导出，不自动生成耕地。
草和花草采用 Minecraft 原生方块，本示例无需外部 schematic 资源。
BIT 图层通过开关接口绘制，数值型图层通过数值接口绘制。群系写入真实的 Biome 图层，和地表材质分别处理。
高度预览的 before/after/delta PNG 表示高度；纯地表或植物操作时，这三张图可以完全相同。
paint_summary 提供每项操作的覆盖格点数量和遮罩预览路径。助手可以叠加这些遮罩，制作彩色分区示意图。
这是规划与覆盖预览，不是 Minecraft 内的截图。实际植物方块在导出 Minecraft 地图时生成。
自检命令：
.\.venv\Scripts\python.exe -m worldpainter_mcp --doctor
.\.venv\Scripts\python.exe -m worldpainter_mcp --self-test
.\.venv\Scripts\python.exe tests\integration_vegetation.py最后一项在本机创建 128×128 临时测试地图，通过真实 MCP 完成计划、预览、写入和读回，核实分区、植物、源文件不变，以及拒绝被篡改的预览。
测试记录保存在包目录下的 work/vegetation-test/。
2026-10-03 在上述环境实际读取并写回 Vágar 8192×8192 工程；写入地表、五类群系与两组原生植物图层。 逐格对照确认高度与水位没有变化，植物覆盖没有落在海域或裸岩上。 这不是实测植被分类或物种调查。植物设置字段依赖 WorldPainter 2.27.1 的实现，升级 WorldPainter 后请先运行真实植物集成测试。 当前工具的重点是工程文件处理；不操控 WorldPainter 窗口，不附带商业树木素材，不自动检索地理水系数据，也不自动完成整张地图的 Minecraft 导出。
官方参考：
WorldPainter 脚本：https://www.worldpainter.net/trac/wiki/Scripting
原生植物图层：https://www.worldpainter.net/javadoc/org/pepsoft/worldpainter/layers/plants/PlantLayer.html
paint_operations 新增 {"type":"water","data_path":"D:\\Maps\\water-target.npz"}。
NPZ 使用 numpy 保存四个同长度一维数组：x、y 是绝对 WorldPainter 整数格点坐标；bed 是浮点床面高度；water 是整数水位。
数据不能包含重复坐标、非有限值或越界坐标。床面必须低于水位，且只能降低现有地面，不允许抬高地面。
水域数据会经过计划、预览、源文件校验、输入文件及编译数据哈希校验，再保存新副本。
预览的高度图包含床面变化；paint_summary 的水域遮罩显示水位操作范围。
要把植物从水域清除，另外添加 layer(layer=现有植物图层名,value=0,mask_path=水域遮罩)；地表材质和群系同样分别绘制。
水位操作只接收准备好的格点数据。它不自行推测湖泊位置，不下载水系，不测量湖底深度，也不是水动力模拟。 请先对齐水域矢量与高程栅格，再制作床面和水位；河道宜保留地形落差并限制开挖深度。 将整张地图导出 Minecraft 后，仍需检查水流更新、瀑布、漏水及水岸观感。
水域真实集成测试：
.\.venv\Scripts\python.exe tests\integration_water.py测试创建小型地图，经过真实 MCP 写入平水湖和阶梯河道，逐格验证保存值及区域外不变；应用缺失预览或被篡改编译文件时会拒绝写入。
本工具采用 MIT License。WorldPainter 与 Python 需分别安装，遵循各自的许可；本仓库不分发它们或地图工程。
Compute elevation and slope statistics, optional coast coverage, and a heightmap preview. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| dimension | No | ||
| sea_level | No | ||
| world_path | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are supplied, so the description carries the full behavioral burden. It does disclose the important safety trait 'Read-only,' which is real value, but it says nothing about cost, runtime, permissions, or what the optional coast-coverage pass actually does.
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 front-loaded sentence covering outputs plus a two-word safety tag — no filler. It is terse rather than padded, though 'Read-only.' as a fragment is slightly abrupt and could be folded in.
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?
An output schema exists, so return values need not be explained. But for a three-parameter analysis tool with zero annotation coverage, the description omits parameter meaning, usage conditions, and any behavioral detail an agent would need to invoke it correctly.
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% for three parameters, and the description does not compensate. 'dimension', 'sea_level', and 'world_path' are never explained; 'sea_level' is only obliquely implied by the mention of coast coverage, leaving formats and valid values undocumented.
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 verb+resource (compute elevation and slope statistics) and enumerates the concrete outputs: coast coverage and a heightmap preview. It does not, however, distinguish itself from siblings like wp_export_heightmap or wp_get_world_info, so an agent must infer the boundary.
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 named alternative. The word 'optional' hints that coast coverage is conditional but never says under what condition, and nothing routes the agent between this and the analysis/export siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply an already previewed plan via WorldPainter, snapshot first, and save a new copy by default.
| Name | Required | Description | Default |
|---|---|---|---|
| plan_id | Yes | ||
| preview_id | Yes | ||
| output_path | No | ||
| overwrite_original | No | ||
| allow_overwrite_output | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose two important side effects: a snapshot is taken first and output is saved to a new copy by default. However, it does not explain what happens when overwrite_original is enabled, what permissions are required, or any failure behavior, leaving the destructive path undocumented.
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, leading with the action and following with the safety-relevant defaults. It is efficient, though quite terse for a tool with this much undisclosed parameter surface.
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 mutation tool with zero annotations, 5 parameters at 0% schema coverage, and no output schema caveat beyond the output schema existing, the description is thin. Return values need not be explained, but the input parameters and the overwrite/destructive path are effectively undocumented.
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% across 5 parameters, so the description must compensate and largely does not. It gestures at the default behavior behind overwrite_original/output_path ('save a new copy by default') but says nothing about plan_id, preview_id, output_path, or allow_overwrite_output semantics.
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 verb and resource ('Apply an already previewed plan via WorldPainter') and adds two behavioral qualifiers (snapshot first, save a new copy). It implicitly distinguishes itself from the preview sibling by requiring an 'already previewed' plan, though it never names wp_preview_terrain_edit or wp_plan_terrain_edit directly.
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?
'Apply an already previewed plan' establishes a clear prerequisite ordering relative to wp_preview_terrain_edit, and 'save a new copy by default' signals the default execution mode. There is no explicit when-not-to-use guidance or named alternative, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export a dimension heightmap to PNG plus lossless bridge data. Dimension may be its selector, name or index.
| Name | Required | Description | Default |
|---|---|---|---|
| dimension | No | ||
| world_path | Yes | ||
| output_path | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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, and it only states the artifact produced. It does not disclose that this writes files to disk, whether output_path is created or overwritten, permission/selector requirements, size or runtime characteristics, or any 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?
Two short sentences, action-first, with zero filler. The parameter clarification follows the purpose statement rather than preceding it, which is the right order.
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?
An output schema exists, so return values need not be restated. However, for a file-writing tool with no annotations and 0% schema coverage, the description should at least address output_path semantics and where the bridge data lives; that context is missing.
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 usefully clarifies that dimension accepts a selector, name, or index — genuinely beyond the schema's bare 'string' — but leaves world_path and output_path (the required path and the output destination) completely undocumented.
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 verb (Export), a specific resource (a dimension heightmap), and the exact outputs produced (PNG plus lossless bridge data). No sibling tool performs export, so the agent can identify this uniquely without opening any 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?
Usage is only implied: an agent can infer this is the tool to call when it needs a heightmap artifact rather than analysis (wp_analyze_terrain) or editing (wp_plan_terrain_edit). There is no explicit when-to-use, no prerequisites, and no named alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a .world project name, platform, dimensions, bounds, height ranges and layer names. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| world_path | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden; it usefully declares 'Read-only', covering the safety profile a readOnlyHint would normally provide. However, it says nothing about failure modes (missing/corrupt .world file) or any behavioral constraints beyond the read-only claim.
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 compact sentences, front-loaded with the verb and the enumerated return fields, with the read-only qualifier at the end. No wasted words.
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?
An output schema exists, so return values need not be re-explained, and the description compensates by listing the returned fields. For a simple read-only getter this is largely complete, with only error behavior and path-format specifics missing.
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?
One required parameter (world_path) with 0% schema description coverage, so the description must compensate. The phrase '.world project' hints that world_path points to a .world file, adding marginal meaning, but there is no detail on path format, relative vs absolute, or validity requirements.
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 (Read) and resource (.world project) and enumerates the exact fields returned (name, platform, dimensions, bounds, height ranges, layer names). It is clearly a metadata getter, distinguishing it from the terrain-editing and snapshot siblings, though it never names a sibling 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?
There is no when-to-use or when-not-to-use guidance and no alternative tool is named. The agent can infer it is a read of project metadata, but nothing tells it when to reach for this over wp_analyze_terrain or wp_export_heightmap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List safety snapshots, optionally restricted to one original .world path.
| Name | Required | Description | Default |
|---|---|---|---|
| world_path | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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 snapshots are read-only, whether listing has any side effects, how many results return, pagination, or ordering. The word 'safety' hints at purpose but conveys no operational behavior.
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 clause that states the action and filter in twelve words. Nothing extraneous, though the terseness leaves gaps that additional precise context could have filled.
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?
An output schema exists, so return values need not be described. For a no-annotation, zero-schema-coverage tool with a sibling that performs the actual rollback, the description is minimally adequate but does not connect listing to the rollback workflow or describe result ordering or scope.
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 0%, but there is only one optional parameter with a default of null. The description explains that world_path restricts results to one original .world path, which is the key semantic the schema lacks. However, it does not clarify format, matching behavior, or what happens when omitted beyond 'optional'.
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 (safety snapshots), and adds the optional filter scope. It does not differentiate itself from the sibling wp_rollback_snapshot, but the listing action is clear from the name and description 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?
The optional 'original .world path' filter implies a use case (enumerate snapshots for one world), but there is no explicit when-to-use guidance, no mention of the relationship to wp_rollback_snapshot as a follow-up action, and no stated preconditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a non-writing edit plan.
Height operation types: smooth(radius,passes,strength), erosion(iterations,talus,strength), ridge_valley(radius,scale,strength), raise_lower(delta,strength), slope_limit(max_slope,iterations,strength), coastline_soften(sea_level,width,radius,strength). Paint operation types: terrain(terrain), layer(layer,value), biome(biome_id), plants(layer, plants=[{name,weight}], density=0.25,seed=1), water(data_path): NPZ with equal 1D arrays x,y (absolute integer world coordinates), bed (float ground height), water (integer water level). Only lowers existing ground. Water does not clear plants or change terrain/biomes; add masked layer/terrain/biome operations. Plants creates a NEW native Custom Plants layer, with valid-block checks and no farmland. Each paint operation may have its own mask_path, intersected with the global mask. Use wp_get_world_info to see existing layer names; plants must use a new name. Region types: rectangle(x,y,width,height,feather), circle(center_x,center_y,radius,feather), or polygon(points,feather). mask_path may point to a grayscale image covering the full dimension. This tool never saves a .world file; preview is mandatory next.
| Name | Required | Description | Default |
|---|---|---|---|
| region | No | ||
| dimension | No | ||
| mask_path | No | ||
| world_path | Yes | ||
| paint_operations | No | ||
| height_operations | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does so well: it states the tool never saves a .world file, that preview is mandatory next, that water only lowers existing ground and does not clear plants or change terrain/biomes, that plants creates a new native layer with valid-block checks and no farmland, and that per-operation masks are intersected with the global mask.
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?
Front-loads the core purpose in one sentence, then organizes details by height operations, paint operations, region types, and masking. Despite its length, every sentence conveys necessary semantic or behavioral information for this complex 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?
Given the tool's complexity, the presence of an output schema (so return values need not be explained), and the absence of annotations, the description is complete enough for an agent to construct a valid plan. It covers operation schemas, masking, region formats, and the mandatory preview handoff, leaving only the minor dimension parameter unaddressed.
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 thoroughly documents the shape of paint_operations and height_operations (with field names and defaults), region types (rectangle, circle, polygon with their fields), and mask_path behavior. It does not explain world_path or dimension, though world_path is largely self-evident.
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+resource: 'Create a non-writing edit plan,' then details the operation types the plan supports. It names wp_get_world_info for layer names and says preview is mandatory next, which routes the agent, but it does not explicitly contrast with wp_apply_terrain_plan or wp_analyze_terrain.
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?
Provides clear workflow context: use wp_get_world_info to see existing layer names, and preview is mandatory next. It implies this is the planning step before preview/apply, but does not explicitly state when to choose this over wp_analyze_terrain or other read tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate before/after/delta PNGs and a one-time preview_id for a plan. Does not write a .world file.
| Name | Required | Description | Default |
|---|---|---|---|
| plan_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well: it discloses non-mutation ('Does not write a .world file') and the ephemeral nature of the returned token ('one-time preview_id'). It still omits where the PNGs are written, how long they persist, and whether a pre-existing plan is required.
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 primary purpose and the key negative constraint both front-loaded. 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?
The output schema exists, so return values need not be spelled out, and the description still previews the PNG outputs and preview_id token. For a single-parameter, non-destructive tool it is nearly sufficient; only the provenance of plan_id and the lifetime of the preview artifacts are missing.
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?
Only one parameter (plan_id) with 0% schema description coverage, so the description is the only source of meaning. 'For a plan' hints the id references a plan, but it never says the id comes from wp_plan_terrain_edit or what format it takes, leaving the one input only half-explained.
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 (Generate) plus the concrete artifacts produced (before/after/delta PNGs, a preview_id) and scopes it to a plan. The closing clause 'Does not write a .world file' sharply distinguishes it from the write-path sibling wp_apply_terrain_plan without needing to name 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?
The phrase 'for a plan' and the non-writing clause make the usage context clear: this is the inspect-first step before committing an edit. It stops short of explicitly naming wp_apply_terrain_plan or wp_plan_terrain_edit as the prerequisites/alternatives, so it falls short of a full when/when-not/alternatives statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restore a snapshot to a new .world copy by default; original overwrite requires explicit opt-in.
| Name | Required | Description | Default |
|---|---|---|---|
| output_path | No | ||
| snapshot_id | Yes | ||
| overwrite_original | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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 discloses the key safety default (new copy) and that overwrite requires opt-in, which is valuable, but omits permissions, reversibility, and side effects of restoring, leaving significant behavioral 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?
Single front-loaded sentence with no filler; it efficiently conveys the core action and default behavior. However, the brevity contributes to parameter and behavioral gaps, so it is not maximally helpful.
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 no annotations, 0% schema coverage, and a mutation action, the description should do more. It does not cover the required snapshot_id, optional output_path, permissions, or side effects. Output schema exists, so return values needn't be explained, but the description remains incomplete for safe 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 coverage is 0%, so the description must compensate for all three parameters. It alludes to overwrite_original ('original overwrite requires explicit opt-in') and default output ('new .world copy'), but never names or explains snapshot_id or output_path, and gives no format or type details.
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 ('Restore') and resource ('snapshot') and includes default output behavior. It does not explicitly differentiate from siblings like wp_list_snapshots or wp_apply_terrain_plan, but the restore action is distinct enough for an agent to identify.
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?
Provides conditional guidance: default creates a new .world copy, and overwrite requires explicit opt-in. It does not state when to use this tool versus listing snapshots or other terrain tools, so usage is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.3.0wp_analyze_terrainwp_apply_terrain_planwp_export_heightmapwp_get_world_infowp_list_snapshotswp_plan_terrain_editwp_preview_terrain_editwp_rollback_snapshotScored across 8 tools
Each tool has a clearly distinct role in the terrain-editing workflow: inspection, export, analysis, planning, previewing, applying, and snapshot management. The plan/preview/apply trio is explicitly sequenced with non-overlapping outputs, so an agent can easily tell them apart.
All tool names follow a consistent wp_ + verb_noun snake_case pattern (wp_get_world_info, wp_export_heightmap, wp_apply_terrain_plan, etc.). The compound nouns like terrain_edit and terrain_plan remain predictable and readable.
Eight tools is well-scoped for a world-editing MCP with a plan-preview-apply safety pipeline and snapshot support. Each tool earns its place without redundancy or bloat.
The surface covers the core lifecycle: read world info, export/analyze terrain, plan/preview/apply edits, and list/rollback snapshots. Minor gaps exist, such as no tool to delete or prune snapshots, but agents can work around these limitations.
Create, edit, render, save, and export voxel models with interactive 3D previews.
Create, inspect, validate, and save editable 3D building scenes with Pascal's hosted MCP server.
Generate authentic pixel art - sprites, animations, and tilesets - from any MCP client
Checks whether generated Minecraft Bedrock content will actually load. Nine read-only tools.