Roblox Studio MCP

Overview Schema Source Related Servers Discussions Admin

Build and edit terrain

terrain

Destructive

Fill solids in Roblox landscape as one undo step to build hills and roads, repaint materials in regions, carve caves with Air, clear areas, and manage custom material slots.

Instructions

Fills, repaints and clears Roblox terrain — hills, water, caves, roads.

Terrain is not made of instances, so none of the instance tools reach it: there is nothing to create, no path for find, and no property for modify. This is the only way to shape it short of writing FillBall calls by hand through execute_luau.

fill takes an ARRAY of solids and applies them as one undo step, which is how terrain is actually built: a hill is several overlapping balls, a road is a row of blocks. Shapes are block (needs size), ball (needs radius), cylinder (needs radius and height) and wedge (needs size).

To CARVE, fill with material Air. That is not a special mode — a cave is a ball of Air inside a hill, and a tunnel is a row of them.

replace swaps one material for another inside a region and leaves the shape alone, which is how you turn a grass hill to snow without rebuilding it. clear empties a region, or everything with confirm=true. stats says whether the place uses terrain at all -- call it first in an unfamiliar place. It cannot say WHERE the terrain is: Roblox exposes no bounding box for it. Take a screenshot to see the shape.

Positions are the centre of the solid, in studs, as "x, y, z". Terrain snaps to a 4-stud voxel grid, so small features come out blockier than the numbers suggest; nothing thinner than about 4 studs survives.

materials manages the place's custom terrain materials: 64 slots, each a base material plus an optional MaterialVariant and a tint. action list | set | reset. Slot writes are NOT undoable, so each result reports the slot's previous value. Painting with a custom slot is done in the Terrain Editor; Roblox does not let plugins fill by slot.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "terrain"
  }
}

Input Schema

Name	Required	Description	Default
`op`	No	'fill' adds solids (use material Air to carve), 'replace' swaps a material in place, 'clear' empties a region or everything, 'stats' reports what is there.	stats
`to`	No	replace only: the material to write instead.
`from`	No	replace only: the material to look for.
`size`	No	replace and clear: extent of the region in studs, e.g. "512, 256, 512".
`slots`	No	materials set/reset: the slots to change.
`action`	No	materials only: list the slots in use (default), set some, or reset some.
`shapes`	No	fill only: the solids to apply, together, as one undo step.
`confirm`	No	clear only: required to empty ALL terrain. Omit it and give `position`/`size` to clear one region instead.
`position`	No	replace and clear: centre of the region, e.g. "0, 0, 0".
`studioId`	No	Target Studio; omit for the active one.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv1.0.0Nov 1, 2026

addedInput schema / properties / action

Added value: +{
+  "description": "materials only: list the slots in use (default), set some, or reset some.",
+  "enum": [
+    "list",
+    "set",
+    "reset"
+  ],
+  "type": "string"
+}

changedInput schema / properties / op / enum

Previous value: -[
-  "fill",
-  "replace",
-  "clear",
-  "stats"
-]New value: +[
+  "fill",
+  "replace",
+  "clear",
+  "stats",
+  "materials"
+]

addedInput schema / properties / slots

Added value: +{
+  "description": "materials set/reset: the slots to change.",
+  "items": {
+    "properties": {
+      "base": {
+        "description": "set: base material, e.g. Grass, Rock.",
+        "type": "string"
+      },
+      "color": {
+        "description": "set: tint, \"#7FA35B\" or \"r, g, b\".",
+        "type": "string"
+      },
+      "slot": {
+        "description": "Slot 2-63. set: omit to take the first free slot.",
+        "maximum": 63,
+        "minimum": 2,
+        "type": "integer"
+      },
+      "variant": {
+        "description": "set: MaterialVariant name for custom textures.",
+        "type": "string"
+      }
+    },
+    "type": "object"
+  },
+  "maxItems": 62,
+  "type": "array"
+}

Addedv0.5.6Sep 10, 2026

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so much of the risk profile is structured. The description still adds real behavioural context beyond them: fill applies all solids as one undo step, `clear` with confirm=true empties everything, custom material slot writes are NOT undoable and each result reports the slot's `previous` value, and the 4-stud voxel grid means sub-4-stud features vanish. Those are genuine non-obvious consequences. Minor gap: no auth/rate-limit/pagination context, though little applies here.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the capability and the instance-tool contrast, then grouped by operation (fill/carve, replace, clear, stats, materials). It is long, and the shape-requirement list in prose duplicates the nested schema, so a sentence or two could be cut, but almost every line carries operationally useful detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers the hard edges an agent would otherwise hit: stats cannot report WHERE terrain is because Roblox exposes no bounding box, screenshot is the workaround, voxel snapping limits small features, and custom slots cannot be painted programmatically. For a 5-op, 10-parameter mutation tool with no output schema, that is enough to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, and the description mostly complements rather than duplicates it: shape/material pairings ("block needs size, ball needs radius, cylinder needs radius and height"), Air as the carve material, and "Positions are the centre of the solid, in studs, as 'x, y, z'". That said, most of this is already restated in the per-property descriptions, so the added value over the schema is modest.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb set and resource ("Fills, repaints and clears Roblox terrain") and explicitly carves out its scope by naming what it is not — instance tools (create/find/modify) cannot reach terrain because terrain has no instances. An agent can distinguish terrain from every sibling without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use routing ("call `stats` first in an unfamiliar place", "take a `screenshot` to see the shape"), names the fallback path (`execute_luau` FillBall), and distinguishes the alternatives inside the tool itself: `fill` with Air to carve vs `replace` to swap material in place vs `clear` for a region. It also states what `replace` is for (grass hill to snow without rebuilding).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server