sbox-mcp-server 1.20.0 → 2.0.0

package/dist/tools/components.js

@@ -24,7 +24,7 @@ export function registerComponentTools(server, bridge) {
         };
     });
     // ── get_all_properties ───────────────────────────────────────────
-    server.tool("get_all_properties", "Dump all public properties of every component on a GameObject as JSON -- names, types, and current values", {
+    server.tool("get_all_properties", "Dump all public properties of every component on a GameObject. Returns { id, components } where each entry is { component, properties: [{ name, type, value }] } — values are stringified (unreadable ones show '<error>'). Use the exact component/property names it reports with set_property or get_property; can be large on component-heavy objects.", {
         id: z.string().describe("GUID of the GameObject"),
     }, async (params) => {
         const res = await bridge.send("get_all_properties", params);
@@ -36,7 +36,7 @@ export function registerComponentTools(server, bridge) {
         };
     });
     // ── list_available_components ────────────────────────────────────
-    server.tool("list_available_components", "List all component types available in s&box (built-in and custom). Search by name or filter by category", {
+    server.tool("list_available_components", "List all instantiable component types in the TypeLibrary — built-in AND your project's custom components (abstract types excluded); filter does a substring match on the type name. Returns { count, components } with { name, title, description, fullName } per type, sorted by name — the unfiltered list is LARGE, so pass filter. Use the returned name with add_component_with_properties, and describe_type for a type's full property list.", {
         filter: z
             .string()
             .optional()

package/dist/tools/debugdraw.js

@@ -28,25 +28,25 @@ export function registerDebugDrawTools(server, bridge) {
         color,
         thickness,
     }, async (p) => reply(await bridge.send("debug_draw_line", p)));
-    server.tool("debug_draw_ray", "Draw a debug ray (drawn as an arrow) from an origin along a direction for a given length. Renders in editor and play. Ideal for visualizing a raycast result or a facing/normal direction. Accumulates until debug_clear.", {
+    server.tool("debug_draw_ray", "Draw a debug ray (drawn as an arrow) from an origin along a direction for a given length. Renders in editor and play. Ideal for visualizing a raycast result or a facing/normal direction. Accumulates until debug_clear. Returns { drawn: 'ray', count, mode } — count is the total accumulated primitives, mode is 'edit' or 'play' (edit-mode gizmos are NOT in take_screenshot; use capture_view in play mode).", {
         origin: z.string().describe('Ray origin, world-space "x,y,z"'),
         direction: z.string().describe('Direction vector "x,y,z" (normalized internally)'),
         length: z.number().optional().describe("Ray length in units (default 64)"),
         color,
         thickness,
     }, async (p) => reply(await bridge.send("debug_draw_ray", p)));
-    server.tool("debug_draw_box", "Draw a wireframe debug box centered at a point. Renders in editor and play. Ideal for visualizing a trigger_zone's bounds or a physics_overlap box volume. Accumulates until debug_clear.", {
+    server.tool("debug_draw_box", "Draw a wireframe debug box centered at a point. Renders in editor and play. Ideal for visualizing a trigger_zone's bounds or a physics_overlap box volume. Accumulates until debug_clear. Returns { drawn: 'box', count, mode } — count is the total accumulated primitives, mode is 'edit' or 'play' (edit-mode gizmos are NOT in take_screenshot; use capture_view in play mode).", {
         center: z.string().describe('Box center, world-space "x,y,z"'),
         size: z.string().optional().describe('Full size "x,y,z" in units (default "32,32,32")'),
         color,
         thickness,
     }, async (p) => reply(await bridge.send("debug_draw_box", p)));
-    server.tool("debug_draw_sphere", "Draw a wireframe debug sphere at a point. Renders in editor and play. Ideal for visualizing a physics_overlap radius or an NPC's hearing/sight range. Accumulates until debug_clear.", {
+    server.tool("debug_draw_sphere", "Draw a wireframe debug sphere at a point. Renders in editor and play. Ideal for visualizing a physics_overlap radius or an NPC's hearing/sight range. Accumulates until debug_clear. Returns { drawn: 'sphere', count, mode } — count is the total accumulated primitives, mode is 'edit' or 'play' (edit-mode gizmos are NOT in take_screenshot; use capture_view in play mode).", {
         center: z.string().describe('Sphere center, world-space "x,y,z"'),
         radius: z.number().optional().describe("Radius in units (default 32)"),
         color,
         thickness,
     }, async (p) => reply(await bridge.send("debug_draw_sphere", p)));
-    server.tool("debug_clear", "Remove all debug-draw primitives by destroying the debug holder for the current scene (edit or play). Call before redrawing a fresh frame of debug shapes.", {}, async (p) => reply(await bridge.send("debug_clear", p)));
+    server.tool("debug_clear", "Remove ALL debug-draw primitives at once by destroying the debug holder for the current scene (edit or play) — there is no way to remove a single shape. Call before redrawing a fresh frame of debug shapes. Returns { cleared, removed } where removed is how many primitives were destroyed.", {}, async (p) => reply(await bridge.send("debug_clear", p)));
 }
 //# sourceMappingURL=debugdraw.js.map

package/dist/tools/diagnostics.js

@@ -281,7 +281,7 @@ export function registerDiagnosticTools(server, bridge) {
         };
     });
     // ── console_run ──────────────────────────────────────────────────── (bridge)
-    server.tool("console_run", "Run an s&box console command / ConCmd via Sandbox.ConsoleSystem.Run — e.g. a cvar ('sv_cheats 1') or a registered command. Also the invocation primitive behind execute_csharp.", {
+    server.tool("console_run", "Run an s&box console command / ConCmd via Sandbox.ConsoleSystem.Run — e.g. a cvar ('sv_cheats 1') or a registered command. Also the invocation primitive behind execute_csharp. Fire-and-forget: returns only { ran, command } and does NOT capture console output — follow with read_log to see what the command printed.", {
         command: z.string().describe("The console command line to run"),
     }, async (params) => {
         const res = await bridge.send("console_run", params);
@@ -310,14 +310,16 @@ export function registerDiagnosticTools(server, bridge) {
         const cmd = `claude_exec_${id}`;
         const filePath = `Editor/__Exec_${id}.cs`;
         const marker = `[EXEC ${id}]`;
+        // Bare `Log` (via `using Sandbox;`), NOT `Sandbox.Log` — the latter stopped
+        // resolving in project editor assemblies on engine 26.07.08b and broke every call.
         const inner = params.expression
-            ? `var __r = (${params.code});\n\t\t\tSandbox.Log.Info( "${marker} RESULT=" + System.Text.Json.JsonSerializer.Serialize( __r ) );`
-            : `${params.code}\n\t\t\tSandbox.Log.Info( "${marker} DONE" );`;
+            ? `var __r = (${params.code});\n\t\t\tLog.Info( "${marker} RESULT=" + System.Text.Json.JsonSerializer.Serialize( __r ) );`
+            : `${params.code}\n\t\t\tLog.Info( "${marker} DONE" );`;
         const cs = `using Editor;\nusing Sandbox;\nusing System;\n\n` +
             `public static class __Exec_${id}\n{\n` +
             `\t[ConCmd( "${cmd}" )]\n\tpublic static void Run()\n\t{\n` +
             `\t\ttry\n\t\t{\n\t\t\t${inner}\n\t\t}\n` +
-            `\t\tcatch ( System.Exception __e ) { Sandbox.Log.Error( "${marker} ERROR=" + __e.Message ); }\n` +
+            `\t\tcatch ( System.Exception __e ) { Log.Error( "${marker} ERROR=" + __e.Message ); }\n` +
             `\t}\n}\n`;
         const timeout = params.timeoutMs ?? 20000;
         const wr = await bridge.send("write_file", { path: filePath, content: cs });
@@ -390,7 +392,7 @@ export function registerDiagnosticTools(server, bridge) {
         };
     });
     // ── get_bounds ─────────────────────────────────────────────────────── (bridge, Batch 33)
-    server.tool("get_bounds", "Get a GameObject's world-space bounding box — center, size, extents, mins/maxs, and a radius. Useful for placing/framing objects and sizing camera moves. Reads GameObject.GetBounds(); objects with no renderer report empty:true with their world position.", {
+    server.tool("get_bounds", "Get a GameObject's world-space bounding box. Returns { id, name, center, size, extents, mins, maxs, radius, position, empty } — objects with no renderer report empty:true (bounds collapse to the world position) plus an explanatory note. Feed center/radius into screenshot_from or frame_camera to frame the object, or use mins/maxs for placement math (screenshot_orbit calls this internally).", {
         id: z.string().describe("GUID of the GameObject to measure"),
     }, async (params) => {
         const res = await bridge.send("get_bounds", params);

package/dist/tools/discovery.js

@@ -19,21 +19,21 @@ export function registerDiscoveryTools(server, bridge) {
         return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     });
     // ── list_libraries ───────────────────────────────────────────────
-    server.tool("list_libraries", "List the s&box libraries/addons installed in this project (reads Libraries/ + each .sbproj). Discovers what's available to build ON — e.g. character controllers (fish.scc = Shrimple Character Controller, facepunch.playercontroller), world/spline/road tools — so you can leverage an installed library (add its components via add_component_with_properties, or generate code against its API) instead of writing from scratch. Returns ident/org/title/type/enabled per library. Read-only.", {}, async () => {
+    server.tool("list_libraries", "List the s&box libraries/addons installed in this project (reads Libraries/ + each .sbproj). Discovers what's available to build ON — e.g. character controllers (fish.scc = Shrimple Character Controller, facepunch.playercontroller), world/spline/road tools — so you can leverage an installed library (add its components via add_component_with_properties, or generate code against its API) instead of writing from scratch. Returns `count` and `libraries` [{folder, ident, org, title, type, enabled}] — ALL libraries, no limit or pagination; `enabled` is false when the library's .sbproj has been disabled (renamed .sbproj.disabled). Read-only.", {}, async () => {
         const res = await bridge.send("list_libraries", {});
         if (!res.success)
             return { content: [{ type: "text", text: `Error: ${res.error}` }] };
         return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     });
     // ── search_types ─────────────────────────────────────────────────
-    server.tool("search_types", "Find types matching a name pattern. Pass components_only=true to filter to Component subclasses only. Useful for discovering 'is there a built-in X for this?'", {
+    server.tool("search_types", "Find loaded types matching a name pattern. Useful for discovering 'is there a built-in X for this?'. Returns `count` and `matches` with each type's name, fullName, isComponent, and isAbstract — results are silently truncated at `limit` (default 50), so narrow the pattern if you hit the cap. Pass a match's name to describe_type for its full member surface.", {
         pattern: z.string().describe("Substring to match against type name (case-insensitive)"),
         namespace: z
             .string()
             .optional()
             .describe("Optional namespace filter (case-insensitive substring)"),
-        components_only: z.boolean().default(false),
-        limit: z.number().int().default(50),
+        components_only: z.boolean().default(false).describe("Only return Component subclasses (default false)"),
+        limit: z.number().int().default(50).describe("Maximum matches to return (default 50); the search stops silently at this cap"),
     }, async (params) => {
         const res = await bridge.send("search_types", params);
         if (!res.success)
@@ -51,10 +51,10 @@ export function registerDiscoveryTools(server, bridge) {
         return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     });
     // ── find_in_project ──────────────────────────────────────────────
-    server.tool("find_in_project", "Grep the user's s&box project for a symbol. Returns file paths and line numbers. Useful for finding usage examples of an API or seeing how the project already does something.", {
+    server.tool("find_in_project", "Grep the user's s&box project for a symbol (case-sensitive substring; skips .git/bin/obj). Useful for finding usage examples of an API or seeing how the project already does something. Returns `symbol`, `count`, and `results` [{file, line, text}], capped at `max_results` (default 25) — raise it if you may be missing hits. Follow up with read_file on a result's file path.", {
         symbol: z.string().describe("Substring or symbol to search for"),
         extension: z.string().default(".cs").describe("File extension filter"),
-        max_results: z.number().int().default(25),
+        max_results: z.number().int().default(25).describe("Maximum hits to return (default 25); the search stops once reached"),
     }, async (params) => {
         const res = await bridge.send("find_in_project", params);
         if (!res.success)

package/dist/tools/gameobjects.js

@@ -70,7 +70,7 @@ export function registerGameObjectTools(server, bridge) {
         };
     });
     // ── duplicate_gameobject ─────────────────────────────────────────
-    server.tool("duplicate_gameobject", "Clone a GameObject with all its components. Optionally offset position or rename", {
+    server.tool("duplicate_gameobject", "Clone a GameObject with all its components. Returns { duplicated, original, gameObject } — gameObject.id is the clone's new GUID; pass it to set_transform / add_component_with_properties. If offset is omitted the clone lands exactly on top of the original.", {
         id: z.string().describe("GUID of the GameObject to duplicate"),
         name: z.string().optional().describe("New name for the clone"),
         offset: Vector3Schema.optional().describe("Position offset from original so the clone doesn't overlap"),
@@ -84,7 +84,7 @@ export function registerGameObjectTools(server, bridge) {
         };
     });
     // ── rename_gameobject ────────────────────────────────────────────
-    server.tool("rename_gameobject", "Change the display name of a GameObject", {
+    server.tool("rename_gameobject", "Change the display name of a GameObject identified by its GUID (the GUID itself never changes, so existing references stay valid). Returns { renamed, id, oldName, newName }. Name-based lookups (e.g. find_objects) will see the new name immediately.", {
         id: z.string().describe("GUID of the GameObject"),
         name: z.string().describe("New display name"),
     }, async (params) => {
@@ -114,7 +114,7 @@ export function registerGameObjectTools(server, bridge) {
         };
     });
     // ── set_enabled ──────────────────────────────────────────────────
-    server.tool("set_enabled", "Enable or disable a GameObject (disabled objects are invisible and inactive)", {
+    server.tool("set_enabled", "Enable or disable a GameObject (disabled objects are invisible and inactive, including their components and children). Returns { id, enabled } confirming the new state.", {
         id: z.string().describe("GUID of the GameObject"),
         enabled: z.boolean().describe("true to enable, false to disable"),
     }, async (params) => {
@@ -127,7 +127,7 @@ export function registerGameObjectTools(server, bridge) {
         };
     });
     // ── set_transform ────────────────────────────────────────────────
-    server.tool("set_transform", "Set position, rotation, and/or scale on a GameObject. Only provided values are changed", {
+    server.tool("set_transform", "Set position, rotation, and/or scale on a GameObject. Only provided values are changed; values apply in world space unless local=true. Returns { transformed, gameObject } with the full serialized object (id, name, position, rotation, scale, components) so you can verify what actually applied.", {
         id: z.string().describe("GUID of the GameObject"),
         position: Vector3Schema.optional().describe("New position"),
         rotation: RotationSchema.optional().describe("New rotation"),
@@ -170,7 +170,7 @@ export function registerGameObjectTools(server, bridge) {
         };
     });
     // ── get_selected_objects ─────────────────────────────────────────
-    server.tool("get_selected_objects", "Get the GameObjects currently selected by the user in the s&box editor", {}, async () => {
+    server.tool("get_selected_objects", "Get the GameObjects currently selected by the user in the s&box editor. Returns { count, selected } where each entry is a serialized GameObject (id, name, enabled, position, rotation, scale, components, childCount) — use the ids with set_transform, add_component_with_properties, etc. Handy for 'do X to what I have selected' requests.", {}, async () => {
         const res = await bridge.send("get_selected_objects");
         if (!res.success) {
             return { content: [{ type: "text", text: `Error: ${res.error}` }] };
@@ -180,7 +180,7 @@ export function registerGameObjectTools(server, bridge) {
         };
     });
     // ── select_object ────────────────────────────────────────────────
-    server.tool("select_object", "Select a GameObject in the editor (highlights it in the hierarchy and scene view)", {
+    server.tool("select_object", "Select a GameObject in the editor (highlights it in the hierarchy and scene view). Replaces the current selection unless addToSelection=true. Returns { selected, id }; confirm the result with get_selected_objects.", {
         id: z.string().describe("GUID of the GameObject to select"),
         addToSelection: z
             .boolean()
@@ -196,7 +196,7 @@ export function registerGameObjectTools(server, bridge) {
         };
     });
     // ── focus_object ─────────────────────────────────────────────────
-    server.tool("focus_object", "Move the editor camera to focus on a specific GameObject (like double-clicking in the hierarchy)", {
+    server.tool("focus_object", "Highlight a GameObject by selecting it in the editor. NOTE: s&box exposes no dedicated focus API, so this only sets the selection — it does NOT move any camera (returns { focused, id, note } saying so). To actually point the viewport at an object use frame_camera; to aim a screenshot use screenshot_from.", {
         id: z.string().describe("GUID of the GameObject to focus"),
     }, async (params) => {
         const res = await bridge.send("focus_object", params);

package/dist/tools/gameplay.js

@@ -109,7 +109,7 @@ export function registerGameplayTools(server, bridge) {
     });
     // ── create_objective_system ───────────────────────────────────────
     // The win/lose primitive — turns "objects in a scene" into "a game with a goal".
-    server.tool("create_objective_system", "Generate an ObjectiveManager component — the win/lose brain of a game. Tracks an objective (collect_all / reach_goal / survive_time / eliminate_all), fires a win, and handles a lose condition (fall below kill-Z / timer / out of lives). Self-contained C#; other systems call ObjectiveManager.Instance. Optionally placed as a scene singleton", {
+    server.tool("create_objective_system", "Generate an ObjectiveManager component — the win/lose brain of a game. Tracks an objective (collect_all / reach_goal / survive_time / eliminate_all), fires a win, and handles a lose condition (fall below kill-Z / timer / out of lives). Self-contained C#; other systems call ObjectiveManager.Instance. Optionally placed as a scene singleton. Returns { created, path, className, gameObject, note } — gameObject is the placed singleton, or null with a note when the fresh type isn't in the TypeLibrary yet. Follow with trigger_hotload, then get_compile_errors; if placement was skipped, place with add_component_to_new_object after the hotload", {
         name: z
             .string()
             .optional()
@@ -310,7 +310,7 @@ export function registerGameplayTools(server, bridge) {
         return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     });
     // -- create_pickup -----------------------------------------------------
-    server.tool("create_pickup", "Generate a trigger-based collectible component. On enter by a tagged object it raises OnCollected (wire it to your objective/score system) and despawns. Optionally builds a visible pickup GameObject with a trigger SphereCollider (+ a model) in one call", {
+    server.tool("create_pickup", "Generate a trigger-based collectible component. On enter by a tagged object it raises OnCollected (wire it to your objective/score system) and despawns. Optionally builds a visible pickup GameObject with a trigger SphereCollider (+ a model) in one call. Returns { created, path, className, gameObject, note } — gameObject is the placed pickup (null unless placeInScene=true); a note flags when the component couldn't attach because the fresh type needs a hotload. Follow with trigger_hotload, then get_compile_errors", {
         name: z.string().optional().describe("Class name. Defaults to 'Pickup'"),
         directory: z
             .string()
@@ -379,7 +379,7 @@ export function registerGameplayTools(server, bridge) {
         return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     });
     // -- create_leaderboard_panel ------------------------------------------
-    server.tool("create_leaderboard_panel", "Generate a Razor PanelComponent that fetches and displays a Sandbox.Services leaderboard derived from a stat name. Produces TWO files: {name}.razor and {name}.razor.scss. The panel auto-refreshes every 30 s, shows rank/displayName/value rows, handles loading state, and includes a BuildHash() override (razor-lint clean). Must be hosted under a ScreenPanel or WorldPanel. Stats must be configured for the project ident on sbox.game. Uses Leaderboards.Get(statName) + board.Refresh() -- the exact API from ServicesQueryHandler.", {
+    server.tool("create_leaderboard_panel", "Generate a Razor PanelComponent that fetches and displays a Sandbox.Services leaderboard derived from a stat name. Produces TWO files: {name}.razor and {name}.razor.scss. The panel auto-refreshes every 30 s, shows rank/displayName/value rows, handles loading state, and includes a BuildHash() override (razor-lint clean). Must be hosted under a ScreenPanel or WorldPanel. Stats must be configured for the project ident on sbox.game. Uses Leaderboards.Get(statName) + board.Refresh() -- the exact API from ServicesQueryHandler. Returns { created, razorPath, scssPath, className, note }. Follow with trigger_hotload, then get_compile_errors, then host it via add_screen_panel (panelComponent=className).", {
         name: z.string().optional().describe("Class name for the panel component. Defaults to 'LeaderboardPanel'"),
         directory: z.string().optional().describe("Subdirectory for the generated files. Defaults to 'Code/UI'"),
         statName: z.string().optional().describe("Sandbox.Services stat name the leaderboard is derived from. Defaults to 'score'"),
@@ -407,7 +407,7 @@ export function registerGameplayTools(server, bridge) {
         return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     });
     // -- create_stat_modifier_system ---------------------------------------
-    server.tool("create_stat_modifier_system", "Generate an enum-keyed stat modifier system with three modifier layers: SET (highest-priority-wins hard override), ADD (summed bonuses), MULT (multiplied factors applied last). Modifier storage uses parallel private Lists of primitive types (serialization-safe). RemoveModifiersFrom(source) cleans up all mods from a buff/debuff source by reference. Static OnStatChanged(stat, value) event fires after every add/remove. Mined from RPG/buff/debuff patterns across shipped s&box games.", {
+    server.tool("create_stat_modifier_system", "Generate an enum-keyed stat modifier system with three modifier layers: SET (highest-priority-wins hard override), ADD (summed bonuses), MULT (multiplied factors applied last). Modifier storage uses parallel private Lists of primitive types (serialization-safe). RemoveModifiersFrom(source) cleans up all mods from a buff/debuff source by reference. Static OnStatChanged(stat, value) event fires after every add/remove. Mined from RPG/buff/debuff patterns across shipped s&box games. Returns { created, path, className, stats, placedOn, note } — stats echoes the sanitized stat names ({name}Stat enum values); placedOn is the target GameObject when attached (needs the type hotloaded). Follow with trigger_hotload, then get_compile_errors.", {
         name: z.string().optional().describe("Class name prefix -- generates {name}Stat enum + {name} Component. Defaults to 'StatSystem'"),
         directory: z.string().optional().describe("Subdirectory for the .cs file. Defaults to 'Code'"),
         stats: z.union([z.array(z.string()), z.string()]).optional().describe("Stat names as a JSON array or comma-separated string. Defaults to 'Health,Speed,Damage'"),

package/dist/tools/inspection.js

@@ -14,7 +14,7 @@ import { z } from "zod";
  */
 export function registerInspectionTools(server, bridge) {
     // ── inspect_networked_object ──────────────────────────────────────
-    server.tool("inspect_networked_object", "Inspect the live networking contract of a GameObject: Network.Owner/IsProxy/IsOwner/Active, OwnerTransfer + OrphanedMode, and every component's [Sync] property names, SyncFlags, and current values (host vs proxy). Unlike get_network_status (session-only), this is per-object — the way to verify a host-authoritative or ownership change actually replicated. Works in edit or play mode.", {
+    server.tool("inspect_networked_object", "Inspect the live networking contract of a GameObject. Returns {id, name, network: {active, isProxy, isOwner, isCreator, ownerId, ownerSteamId, ownerTransfer, orphaned, flags}, components: [{component, fields: [{name, type, isSync, syncFlags, value}]}]} — by default only [Sync]-marked fields are listed (components with none are omitted). Unlike get_network_status (session-only), this is per-object — the way to verify a host-authoritative or ownership change actually replicated; works in edit or play mode. Follow up with set_ownership to change the owner, or networking_lint to find the code-level cause of a bad [Sync] value.", {
         id: z.string().describe("GUID of the GameObject to inspect"),
         allProps: z
             .boolean()
@@ -70,8 +70,8 @@ export function registerInspectionTools(server, bridge) {
         return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     });
     // ── save_inspect ──────────────────────────────────────────────────
-    server.tool("save_inspect", "Inspect the game's FileSystem.Data save files — the assistant is otherwise blind to persisted state. action='list' enumerates files under a folder (with size/mtime); action='read' dumps a save file's JSON; action='diff' compares two save files key-by-key. Use to verify a save actually wrote, debug a load/migration, or confirm a sanitize/clamp ran.", {
-        action: z.enum(["list", "read", "diff"]).default("list"),
+    server.tool("save_inspect", "Inspect the game's FileSystem.Data save files — the assistant is otherwise blind to persisted state. action='list' (default) returns `directories` and `files` [{name, path, size}] under `path` (omit path for the Data root); action='read' returns {path, length, content}, truncating content at 60,000 chars; action='diff' compares two save files key-by-key, returning `diffCount` and up to 200 `diffs` [{key, change: added|removed|changed}]. Use to verify a save actually wrote, debug a load/migration, or confirm a sanitize/clamp ran.", {
+        action: z.enum(["list", "read", "diff"]).default("list").describe("'list' (default) enumerates a folder; 'read' dumps one file's JSON; 'diff' compares `path` vs `pathB`"),
         path: z
             .string()
             .optional()
@@ -87,8 +87,8 @@ export function registerInspectionTools(server, bridge) {
         return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     });
     // ── services_query ────────────────────────────────────────────────
-    server.tool("services_query", "Read from Sandbox.Services — the cloud stats/leaderboard layer many games use as their real DB. action='stats' lists/reads the project's stat definitions and the local player's values; action='leaderboard' fetches a leaderboard board's top entries. Read-only. Use to verify a Stats.Increment/SetValue path or a leaderboard wired correctly.", {
-        action: z.enum(["stats", "leaderboard"]).default("stats"),
+    server.tool("services_query", "Read from Sandbox.Services — the cloud stats/leaderboard layer many games use as their real DB. action='stats' with `name` returns the local player's stat {ident, value, sum, min, max, lastValue, valueString}; without `name` it returns only the package ident plus a usage note (it does NOT list stat definitions). action='leaderboard' (name required) returns {board, displayName, totalEntries, count, entries} with at most `limit` entries (default 10). Read-only; use to verify a Stats.Increment/SetValue path or a leaderboard wired correctly.", {
+        action: z.enum(["stats", "leaderboard"]).default("stats").describe("'stats' (default) reads a local-player stat by `name`; 'leaderboard' fetches a board's top entries"),
         name: z
             .string()
             .optional()
@@ -101,7 +101,7 @@ export function registerInspectionTools(server, bridge) {
         return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     });
     // ── simulate_input ────────────────────────────────────────────────
-    server.tool("simulate_input", "Synthesize player input during PLAY mode so behavior can be verified without a human at the keyboard: press/hold/release a named input action (e.g. 'jump','attack1','use','reload') and/or set AnalogMove / AnalogLook for a duration. Drives movement, IPressable interactions, weapon fire/cooldown/reload, vehicle controls, and HUD advance-on-click. Requires play mode.", {
+    server.tool("simulate_input", "Press or release a named input action during PLAY mode (via Sandbox.Input.SetAction) so input-driven behavior — jump, attack1, use, reload, IPressable, weapon fire — can be verified without a human at the keyboard. REQUIRES play mode and a named `action`; returns {action, state: 'down'|'up', note}. Caveats: SetAction applies to the current input frame ('press' and 'hold' both set the action down; 'release' clears it), and analogMove/analogLook/durationMs are accepted but IGNORED — Sandbox.Input has no analog injection API, so for movement use drive_player or the playtest harness instead.", {
         action: z
             .string()
             .optional()

package/dist/tools/leveltools.js

@@ -28,7 +28,7 @@ const ColorSchema = z
     .describe('RGBA colour — object {r,g,b,a} (0-1) OR comma string "r,g,b,a"');
 export function registerLevelTools(server, bridge) {
     // ── snap_to_ground ─────────────────────────────────────────────────
-    server.tool("snap_to_ground", "Drop a GameObject straight down onto the surface below it (physics raycast). Works best on collider-less props (an object with its own collider may self-hit). Optional offset lifts it off the surface.", {
+    server.tool("snap_to_ground", "Drop a GameObject straight down onto the surface below it (physics raycast). Works best on collider-less props (an object with its own collider may self-hit). Optional offset lifts it off the surface. Returns { snapped, groundZ, gameObject } with the object's updated transform — or { snapped: false, reason } (not an error) when no ground was hit below.", {
         id: z.string().describe("GUID of the GameObject to snap"),
         offset: z.number().optional().describe("Height above the surface to place it (default 0)"),
         startHeight: z.number().optional().describe("How far above the object to start the trace (default 2000)"),
@@ -43,7 +43,7 @@ export function registerLevelTools(server, bridge) {
         };
     });
     // ── align_objects ──────────────────────────────────────────────────
-    server.tool("align_objects", "Align several GameObjects on one axis so they share a coordinate. mode = first (match the first object), min, max, or average.", {
+    server.tool("align_objects", "Align several GameObjects on one axis so they share a coordinate. mode = first (match the first object), min, max, or average; defaults to first. Returns { aligned, axis, mode, target } — aligned is the object count and target the shared coordinate; verify positions with get_scene_hierarchy or a screenshot.", {
         ids: z.array(z.string()).describe("GUIDs of the GameObjects to align (>= 2)"),
         axis: z.enum(["x", "y", "z"]).describe("Axis to align on"),
         mode: z
@@ -60,7 +60,7 @@ export function registerLevelTools(server, bridge) {
         };
     });
     // ── distribute_objects ─────────────────────────────────────────────
-    server.tool("distribute_objects", "Evenly space GameObjects along an axis between the lowest and highest (keeps the two ends fixed, spreads the rest evenly).", {
+    server.tool("distribute_objects", "Evenly space GameObjects along an axis between the lowest and highest (keeps the two ends fixed, spreads the rest evenly). Returns { distributed, axis, from, to } — the object count and the fixed end coordinates the rest were spread between.", {
         ids: z.array(z.string()).describe("GUIDs of the GameObjects to distribute (>= 3)"),
         axis: z.enum(["x", "y", "z"]).describe("Axis to distribute along"),
     }, async (params) => {
@@ -104,7 +104,7 @@ export function registerLevelTools(server, bridge) {
         };
     });
     // ── scatter_props ──────────────────────────────────────────────────
-    server.tool("scatter_props", "Scatter N copies of a model randomly within a radius around a center point — instant foliage, rocks, debris. Each copy gets a random yaw and (by default) is snapped to the ground. Seeded for reproducibility; copies are grouped under one parent by default. Count capped at 300.", {
+    server.tool("scatter_props", "Scatter N copies of a model randomly within a radius around a center point — instant foliage, rocks, debris. Each copy gets a random yaw and (by default) is snapped to the ground. Seeded for reproducibility; copies are grouped under one parent by default. Count capped at 300. Returns { scattered, groupId, seed } — individual prop GUIDs are not returned, so use groupId with get_scene_hierarchy (rootId) to enumerate them, or with set_transform/delete_gameobject to move/remove the whole batch.", {
         model: z.string().describe("Model path to scatter, e.g. 'models/dev/box.vmdl'"),
         center: Vector3Schema.optional().describe("Centre of the scatter area (default origin)"),
         radius: z.number().optional().describe("Scatter radius in units (default 256)"),
@@ -129,7 +129,7 @@ export function registerLevelTools(server, bridge) {
         };
     });
     // ── randomize_transforms ───────────────────────────────────────────
-    server.tool("randomize_transforms", "Add natural variation to existing objects: random yaw and/or random uniform scale within a range. Great for breaking up repetition in placed foliage/rocks/crates. Seeded.", {
+    server.tool("randomize_transforms", "Add natural variation to existing objects: random yaw and/or random uniform scale within a range. Great for breaking up repetition in placed foliage/rocks/crates. Seeded — the same seed reproduces the same layout. Returns { randomized, seed } (the count of objects changed); scale only varies when scaleMax > scaleMin.", {
         ids: z.array(z.string()).describe("GUIDs of the GameObjects to randomize"),
         randomYaw: z.boolean().optional().describe("Randomize Z rotation (default true)"),
         scaleMin: z.number().optional().describe("Min uniform scale (default 1)"),

package/dist/tools/materials.js

@@ -5,7 +5,7 @@ import { z } from "zod";
  */
 export function registerMaterialTools(server, bridge) {
     // ── assign_model ─────────────────────────────────────────────────
-    server.tool("assign_model", "Set a 3D model on a GameObject's ModelRenderer. Creates the renderer component if it doesn't exist", {
+    server.tool("assign_model", "Set a 3D model on a GameObject's ModelRenderer. Creates the renderer component if it doesn't exist; errors if the model path can't be loaded. Returns { assigned, id, model } — follow with assign_material / set_material_property to style it, or take a screenshot to verify.", {
         id: z.string().describe("GUID of the GameObject"),
         model: z
             .string()
@@ -20,7 +20,7 @@ export function registerMaterialTools(server, bridge) {
         };
     });
     // ── create_material ──────────────────────────────────────────────
-    server.tool("create_material", "Create a new material file (.vmat) with a shader and properties like color, roughness, metallic, texture", {
+    server.tool("create_material", "Create a new material file (.vmat, KV1 format) with a shader and properties like color, roughness, metallic, texture. Errors if the file already exists; when no properties are given it writes sensible PBR defaults (g_flMetalness 0, g_flRoughness 1). Returns { created, path, shader, propertiesWritten } — pass the returned path to recompile_asset (so the editor compiles it) and then assign_material.", {
         path: z
             .string()
             .describe("Relative path for the material (e.g. 'materials/walls/brick.vmat')"),
@@ -42,7 +42,7 @@ export function registerMaterialTools(server, bridge) {
         };
     });
     // ── assign_material ──────────────────────────────────────────────
-    server.tool("assign_material", "Apply a material to a ModelRenderer on a GameObject. Optionally target a specific material slot", {
+    server.tool("assign_material", "Apply a material to a GameObject by setting its ModelRenderer's MaterialOverride (overrides the whole model's material). Requires an existing ModelRenderer (assign_model first) and errors if the material path can't be loaded. Returns { assigned, id, material } — tweak values afterwards with set_material_property.", {
         id: z.string().describe("GUID of the GameObject"),
         material: z
             .string()
@@ -61,7 +61,7 @@ export function registerMaterialTools(server, bridge) {
         };
     });
     // ── set_material_property ────────────────────────────────────────
-    server.tool("set_material_property", "Change a property on the material assigned to a GameObject — color, roughness, metallic, texture, etc.", {
+    server.tool("set_material_property", "Change a property on the material assigned to a GameObject — color, roughness, metallic, texture, etc. Operates on the ModelRenderer's MaterialOverride; if none is assigned it auto-creates one from the default complex shader (no separate assign_material step needed). Returns { set, id, property, autoCreatedMaterial } — screenshot to verify the visual change.", {
         id: z.string().describe("GUID of the GameObject"),
         property: z
             .string()

package/dist/tools/moviemaker.js

@@ -14,7 +14,7 @@ import { z } from "zod";
  */
 export function registerMovieMakerTools(server, bridge) {
     // ── list_movies ───────────────────────────────────────────────────
-    server.tool("list_movies", "List the project's .movie resources (Sandbox.MovieMaker clips authored in the editor's Movie Maker dock: Window → Movie Maker). Returns each movie's asset-relative path, whether it currently loads via ResourceLibrary, and whether it has a compiled clip. Start here before add_movie_player / play_movie — and if the list is empty, the movie has to be authored in the dock first (the bridge plays movies; it doesn't author keyframes).", {}, async () => {
+    server.tool("list_movies", "List the project's .movie resources (Sandbox.MovieMaker clips authored in the editor's Movie Maker dock: Window → Movie Maker). Scans the ENTIRE Assets folder recursively and returns every .movie found — no limit or paging. Returns { count, movies, note } where each movie has { path (asset-relative — the form add_movie_player/play_movie expect), name, loadable (resolves via ResourceLibrary), hasCompiledClip }. Start here before add_movie_player / play_movie — if the list is empty, the movie has to be authored in the dock first (the bridge plays movies; it doesn't author keyframes).", {}, async () => {
         const res = await bridge.send("list_movies", {});
         if (!res.success) {
             return { content: [{ type: "text", text: `Error: ${res.error}` }] };

package/dist/tools/networking.js

@@ -8,23 +8,23 @@ import { z } from "zod";
  */
 export function registerNetworkingTools(server, bridge) {
     // ── add_network_helper ────────────────────────────────────────────
-    server.tool("add_network_helper", "Add a NetworkHelper component to the scene for quick multiplayer setup. Handles lobby creation and player prefab spawning", {
+    server.tool("add_network_helper", "Add a NetworkHelper component (with StartServer=true) to an existing GameObject for quick multiplayer setup — at runtime it creates the lobby and spawns the player prefab per connection. Returns { added, id, component:'NetworkHelper' }. NOTE: the current handler requires id (create a holder with create_gameobject first) and does not apply maxPlayers/playerPrefab — wire PlayerPrefab afterward with set_prefab_ref/set_property", {
         id: z
             .string()
             .optional()
-            .describe("GUID of existing GameObject. Creates new if omitted"),
+            .describe("GUID of the GameObject to attach to. Required in practice — the current handler errors when omitted (create a holder with create_gameobject first)"),
         name: z
             .string()
             .optional()
-            .describe("Name for the network manager object. Defaults to 'Network Manager'"),
+            .describe("Rename the target GameObject to this. Omit to keep its current name"),
         maxPlayers: z
             .number()
             .optional()
-            .describe("Maximum number of players in the lobby"),
+            .describe("Maximum number of players in the lobby (currently not applied by the handler)"),
         playerPrefab: z
             .string()
             .optional()
-            .describe("Path to the player prefab to spawn for each connection"),
+            .describe("Path to the player prefab to spawn for each connection (currently not applied by the handler — set the NetworkHelper's PlayerPrefab afterward with set_prefab_ref)"),
     }, async (params) => {
         const res = await bridge.send("add_network_helper", params);
         if (!res.success) {
@@ -35,23 +35,23 @@ export function registerNetworkingTools(server, bridge) {
         };
     });
     // ── configure_network ─────────────────────────────────────────────
-    server.tool("configure_network", "Configure networking settings on the existing NetworkHelper: max players, lobby name, player prefab, start server", {
+    server.tool("configure_network", "Configure lobby settings on Sandbox.Networking. Currently only lobbyName is applied (sets Networking.ServerName) — Networking.MaxPlayers is read-only on this SDK, and playerPrefab/startServer are not applied by the handler (use add_network_helper + set_prefab_ref for those). Returns { configured, maxPlayers, serverName } reflecting the live Networking values", {
         maxPlayers: z
             .number()
             .optional()
-            .describe("Maximum number of players"),
+            .describe("Maximum number of players (currently not applied — Networking.MaxPlayers is read-only on this SDK; the live value is echoed in the response)"),
         lobbyName: z
             .string()
             .optional()
-            .describe("Display name for the lobby"),
+            .describe("Display name for the lobby (sets Networking.ServerName — the only setting this handler applies)"),
         playerPrefab: z
             .string()
             .optional()
-            .describe("Path to the player prefab"),
+            .describe("Path to the player prefab (currently not applied by the handler — set the NetworkHelper's PlayerPrefab via set_prefab_ref instead)"),
         startServer: z
             .boolean()
             .optional()
-            .describe("Start the server/lobby immediately"),
+            .describe("Start the server/lobby immediately (currently not applied by the handler — add_network_helper sets StartServer=true on the NetworkHelper)"),
     }, async (params) => {
         const res = await bridge.send("configure_network", params);
         if (!res.success) {
@@ -62,7 +62,7 @@ export function registerNetworkingTools(server, bridge) {
         };
     });
     // ── get_network_status ────────────────────────────────────────────
-    server.tool("get_network_status", "Check the current multiplayer status: connection state, player count, lobby info, networked objects", {}, async (params) => {
+    server.tool("get_network_status", "Check the current multiplayer status. Returns { isActive, isHost, isClient, isConnecting, maxPlayers, serverName } read from Sandbox.Networking — meaningful mostly in play mode with networking active. It does NOT return a player list or networked-object dump; use inspect_networked_object for a specific object's Network/[Sync] state", {}, async (params) => {
         const res = await bridge.send("get_network_status", params);
         if (!res.success) {
             return { content: [{ type: "text", text: `Error: ${res.error}` }] };
@@ -72,7 +72,7 @@ export function registerNetworkingTools(server, bridge) {
         };
     });
     // ── network_spawn ─────────────────────────────────────────────────
-    server.tool("network_spawn", "Network-enable a GameObject so it is synchronized across all connected clients. Calls NetworkSpawn()", {
+    server.tool("network_spawn", "Network-enable a GameObject so it is synchronized across all connected clients. Calls NetworkSpawn(). Returns { spawned, id } on success — follow with inspect_networked_object to confirm the Network state, or set_ownership to hand it to a connection", {
         id: z.string().describe("GUID of the GameObject to network"),
     }, async (params) => {
         const res = await bridge.send("network_spawn", params);
@@ -84,12 +84,12 @@ export function registerNetworkingTools(server, bridge) {
         };
     });
     // ── set_ownership ─────────────────────────────────────────────────
-    server.tool("set_ownership", "Transfer network ownership of a GameObject to a different connection, or take/drop ownership", {
+    server.tool("set_ownership", "Assign network ownership of a GameObject to a connection, or drop ownership. Omitting connectionId (or passing an empty string) calls Network.DropOwnership(); passing a connection Id or SteamId calls Network.AssignOwnership() on the matching live Connection. Returns { ownershipAssigned, id, connectionId } or { ownershipDropped, id }; errors if no connection matches (connections only exist while networking is active)", {
         id: z.string().describe("GUID of the networked GameObject"),
         connectionId: z
             .string()
             .optional()
-            .describe("GUID of the target connection. Empty string = drop ownership. Omit = take ownership"),
+            .describe("Connection Id GUID or SteamId of the target connection. Omit OR pass an empty string to DROP ownership (there is no take-ownership mode in the current handler)"),
     }, async (params) => {
         const res = await bridge.send("set_ownership", params);
         if (!res.success) {
@@ -100,7 +100,7 @@ export function registerNetworkingTools(server, bridge) {
         };
     });
     // ── add_sync_property ─────────────────────────────────────────────
-    server.tool("add_sync_property", "Annotate an EXISTING public property in a C# script with the [Sync] attribute so s&box replicates it across the network. This does NOT create a new property — the property named by `propertyName` must already be declared in the file; the tool only inserts the [Sync] attribute above it", {
+    server.tool("add_sync_property", "Annotate an EXISTING public property in a C# script with the [Sync] attribute so s&box replicates it across the network. This does NOT create a new property — the property named by `propertyName` must already be declared in the file; the tool only inserts the [Sync] attribute above it. Returns { added, path, property, attribute } — attribute echoes the exact [Sync...] emitted; errors if the property already has [Sync] or isn't found. Follow with trigger_hotload, then get_compile_errors", {
         path: z
             .string()
             .describe("Relative path to the script file (e.g. 'code/Player.cs')"),
@@ -156,7 +156,7 @@ export function registerNetworkingTools(server, bridge) {
         };
     });
     // ── create_networked_player ───────────────────────────────────────
-    server.tool("create_networked_player", "Generate a network-aware player controller with [Sync] properties, owner-only input, and [Rpc.Broadcast] actions", {
+    server.tool("create_networked_player", "Generate a network-aware player controller with [Sync] properties, owner-only input, and [Rpc.Broadcast] actions. Writes <name>.cs and returns { created, path, className }. The generated Component syncs PlayerName/Health, moves a CharacterController from Input.AnalogMove behind an IsProxy guard, and exposes a [Property] MoveSpeed plus an [Rpc.Broadcast] TakeDamage(int). Follow with trigger_hotload, then get_compile_errors, then attach + network_spawn", {
         name: z
             .string()
             .optional()
@@ -165,11 +165,11 @@ export function registerNetworkingTools(server, bridge) {
             .string()
             .optional()
             .describe("Subdirectory under code/"),
-        moveSpeed: z.number().optional().describe("Movement speed. Defaults to 300"),
+        moveSpeed: z.number().optional().describe("Movement speed (generated MoveSpeed [Property]). Defaults to 200"),
         includeHealth: z
             .boolean()
             .optional()
-            .describe("Include health/damage system with host-authoritative TakeDamage. Defaults to true"),
+            .describe("Currently not applied by the handler — the [Sync] Health and [Rpc.Broadcast] TakeDamage are always generated"),
     }, async (params) => {
         const res = await bridge.send("create_networked_player", params);
         if (!res.success) {
@@ -180,7 +180,7 @@ export function registerNetworkingTools(server, bridge) {
         };
     });
     // ── create_lobby_manager ──────────────────────────────────────────
-    server.tool("create_lobby_manager", "Generate a lobby manager script with create/join/leave lobby, player spawning, and connection cleanup", {
+    server.tool("create_lobby_manager", "Generate a lobby manager Component implementing Component.INetworkListener: a static Instance singleton, a [Sync] PlayerCount maintained in OnActive/OnDisconnected, and a LobbyState [Property] that flips to 'playing' when the lobby fills. Writes <name>.cs and returns { created, path, className }. Follow with trigger_hotload, then get_compile_errors, then place via add_component_to_new_object", {
         name: z
             .string()
             .optional()
@@ -192,7 +192,7 @@ export function registerNetworkingTools(server, bridge) {
         maxPlayers: z
             .number()
             .optional()
-            .describe("Default max players. Defaults to 8"),
+            .describe("Currently not applied by the handler — the generated MaxPlayers [Property] defaults to 16; tune it per-instance with set_property"),
     }, async (params) => {
         const res = await bridge.send("create_lobby_manager", params);
         if (!res.success) {
@@ -203,7 +203,7 @@ export function registerNetworkingTools(server, bridge) {
         };
     });
     // ── create_network_events ─────────────────────────────────────────
-    server.tool("create_network_events", "Generate a network event handler script implementing INetworkListener for connect/disconnect/chat events", {
+    server.tool("create_network_events", "Generate a network event relay Component: [Rpc.Broadcast] SendEvent(eventName, payload) to all clients and [Rpc.Host] SendEventToHost(...), both dispatching into a local OnNetworkEvent switch you extend. It does NOT implement INetworkListener — use create_lobby_manager for connect/disconnect hooks. Writes <name>.cs and returns { created, path, className }. Follow with trigger_hotload, then get_compile_errors", {
         name: z
             .string()
             .optional()
@@ -215,7 +215,7 @@ export function registerNetworkingTools(server, bridge) {
         includeChat: z
             .boolean()
             .optional()
-            .describe("Include a chat message broadcast system. Defaults to false"),
+            .describe("Currently not applied by the handler — no chat system is generated"),
     }, async (params) => {
         const res = await bridge.send("create_network_events", params);
         if (!res.success) {