Build, run and publish 3D games in the Zero engine from Claude Code, Cursor or Codex, over MCP.
Scored across 42 tools
Several clusters overlap heavily: three code-execution paths (bash for shell, execute for Luau, tool_exec for JS over the tool catalogue), four ways to get a world in front of the user (world.open, world.open_in_browser, world.launch, world.connect/session.connect), and three presentation setters (set_world_cover, world.set_media, edit_world_metadata). The descriptions are unusually long and explicitly cross-reference each other ('this is the mode flip — to change a file, use edit_file'), which rescues most choices, but the boundaries between entry-point tools still require careful reading rather than being obvious.
Namespaced families (world.*, session.*, zeromind.*) use a consistent verb_noun pattern internally, and the bare engine primitives (read_file, write_file, edit_file, search_tools, describe_tool, tool_exec) are snake_case throughout. Deviations are minor: world-presentation tools are split across prefixes (set_world_cover and edit_world_metadata sit bare while world.set_media is namespaced), and bare `edit` (mode flip) reads oddly next to `edit_file` (file edit).
42 tools is well past a comfortable surface for an agent to hold in view, and the bulk is concentrated in world lifecycle (create/list/open/connect/launch/open_in_browser/delete/trash/restore/fork/undraft/disconnect), where several entries could be merged into one 'open or resolve a world' tool with a mode argument. The domain is genuinely broad — engine control, content library, world lifecycle, meta-tools — so it is not arbitrary bloat, but the count still exceeds what this scope justifies.
Coverage is strong: world CRUD plus trash/restore/fork/undraft, engine mode control, rendering and capture, file read/write/edit, content discovery (search/inspect/preview/install), identity, and analytics. The visible gaps are branch operations (branch selection is explicitly noted as 'coming', and no branch create/switch tool exists) and file deletion/versioning, which are left to bash/zm rather than exposed as tools.
Open an ENGINE skill — a packaged procedure for one job in this world, carrying the instructions plus the assets, guides, and tools that job runs through. These live in the connected world, not in your host environment, and this tool is the only way to open one. Call with NO arguments to list every skill this world knows (name + one-line description, and which you already have open); pass name to open one and get its full instructions, its dependencies marked present or missing here, the exact tool names to call, and any subskills under it (addressed "parent/sub"). A skill you open STAYS OPEN: it and its subskills ride your tool responses, each subskill marked as you open it, so a job spanning many calls keeps its remaining passes in view — pass release when the whole job is done ("*" closes all). Reach for this BEFORE working out a multi-step engine job from first principles — a skill is the already-correct path.
| Name | Required | Description | Default |
|---|---|---|---|
| as | No | Your own name, when you are one of several agents sharing one connection to this engine (the sub-agents one agent session runs share its connection, so without it the engine sees all of them as one caller). Pass the same name on every call you make. The engine then treats you as a caller of your own: your roster name is this name, and your play session, the play-shadow writes and refusals that say who wrote what, engine.modeOwner, your shell session and your notices are yours alone. Lowercase letters, digits, '-' and '_'. Leave it out when you are the only agent on your connection. | |
| name | No | Skill to open, e.g. "scenes". Address a subskill through its parent: "scenes/player-setup". OMIT to list every available skill with its one-line description. | |
| scope | No | When listing, show only skills from this scope: 'builtin' (shipped with the engine), 'world' (authored in the bound world), 'library' (installed). Omit for all of them. Ignored when `name` is given. | |
| release | No | Close a skill you have open, e.g. "scenes" — it stops riding your tool responses. Releasing a parent releases the subskills opened under it. Pass "*" to close every skill you have open. Takes precedence over `name`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare a non-read-only, open-world, non-idempotent, non-destructive profile; the description goes well beyond that with the critical lifecycle trait that an opened skill "STAYS OPEN" and rides tool responses, that subskills are marked as opened, and that `release` (with "*") tears it down. It also discloses that `release` takes precedence over `name` and that the skill lives in the connected world, not the host.
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 definition of a skill and then moves through the call modes in a logical order. It is dense and paragraph-length, with a few flourishes ("this tool is the only way to open one", "a skill is the already-correct path") that add emphasis rather than information.
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?
There is no output schema, and the description compensates by specifying what a list returns (name + one-line description + which are already open) and what opening returns (full instructions, dependency presence, exact tool names, subskills). For a 4-parameter, zero-required, dual-mode tool, nothing an agent needs before calling 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 100% and every parameter (`as`, `name`, `scope`, `release`) is already documented in depth, including the subskill "parent/sub" addressing and the enum values. The description restates the list-vs-open dual mode and release precedence without adding syntax or constraints the schema lacks, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource — "Open an ENGINE skill" — and defines what a skill is ("a packaged procedure for one job in this world, carrying the instructions plus the assets, guides, and tools"). It also distinguishes itself from siblings by asserting it is "the only way to open one" and by contrasting with deriving a job "from first principles."
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?
Gives concrete context for use: no-argument call to list, `name` to open, `release` when the whole job is done, and a clear routing rule — "Reach for this BEFORE working out a multi-step engine job from first principles." It stops short of naming sibling tools (guides, use_tool, describe_tool) or stating when NOT to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A complete bash shell running inside the Zero engine, over this world's files and the engine's live state. It runs in the engine, apart from the computer you are called from. Use it the way you use bash on any development machine, and reach for what you already know first: the shell language is all there, and the standard programs are installed (ls /usr/bin lists them). command not found means only that one program is absent; do that job another ordinary way.
Where things are: the world's project is /zero/source, the engine's live state is /zero/runtime (as files), the engine's documentation is /zero/docs (and man <topic>). /tmp is scratch for the session; ~ is your home, kept on this machine and synced to no one.
The engine's own operations are a command-line program, zero. Learn it as you would any unfamiliar CLI: zero --help, zero --search <query>, zero <toolbox> <tool> --help. zm is the world's version control, with the git verbs. luau <file> runs a Luau script in the engine.
For example: rg -n 'typed function' /zero/source find /zero/source -name '*.luau' | xargs grep -n 'asset.resolve' COUNT="$(find /zero/source -type f | wc -l)"; echo "$COUNT" mkdir -p /tmp/work && grep -rn 'TODO' /zero/source > /tmp/work/todo.txt find /zero/runtime -maxdepth 2 -type d zero --search 'raycast' zero camera --help
| Name | Required | Description | Default |
|---|---|---|---|
| as | No | Your own name, when you are one of several agents sharing one connection to this engine (the sub-agents one agent session runs share its connection, so without it the engine sees all of them as one caller). Pass the same name on every call you make. The engine then treats you as a caller of your own: your roster name is this name, and your play session, the play-shadow writes and refusals that say who wrote what, engine.modeOwner, your shell session and your notices are yours alone. Lowercase letters, digits, '-' and '_'. Leave it out when you are the only agent on your connection. | |
| command | Yes | The command line, written exactly as you would type it into bash anywhere else: pipelines, redirection, `$(...)`, quoting, globs, loops and multi-line scripts all work. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and openWorldHint=true, and the description adds substantial context beyond them: the shell runs inside the engine not on the caller's machine, /tmp is session scratch, ~ is local-only and 'synced to no one', and `command not found` means only that one program is missing. This is unusually rich operational disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded, and the layout (where things are, the `zero`/`zm`/`luau` CLIs, then worked examples) is scannable. It is on the long side, but most sentences carry distinct information rather than padding.
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 complex, open-ended shell tool with no output schema, the description supplies everything needed: filesystem layout, discoverability via `--help`/`--search`, scratch/home semantics, and examples. An agent can invoke it correctly without further context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description adds meaning by explaining what the `command` string can contain (pipelines, redirection, $(...), globs, loops, multi-line scripts) and by tying the `as` parameter to the notion of a per-caller shell session. It reinforces but does not fully re-document the parameters, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb+resource: 'A complete bash shell running inside the Zero engine, over this world's files and the engine's live state.' It distinguishes itself from siblings like execute/read_file/write_file by framing itself as a full shell over the world's files, so an agent understands it is not a task-specific helper.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives strong positive guidance ('Use it the way you use bash on any development machine, and reach for what you already know first') plus concrete examples, and tells the agent where things live. It stops short of naming when to prefer siblings like execute or read_file over running a shell command, so it lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render an image or collage from the engine, or read the frame it presented (source='presented': the game view exactly as the player saw it, with its real TAA, motion blur, exposure and render scale; source='window': the whole window). Pick WHERE with 'source' (and aim it with 'viewpoint' + 'basis': front/top/left/iso against the subject's own axes or the world's), WHAT with 'pass' (motion_vectors to see whether something moves, normal to see whether a surface is correct), HOW it projects with 'projection' ('orthographic' keeps parallel edges parallel and equal sizes equal: the one to verify a shape under), and which render layers with 'renderLayers'. 'isolate' draws the subject without the other geometry. mode='collage' makes a grid whose cells vary by 'setups', by 'viewpoints', by 'passes', or over 'duration': a shot list's whole set-ups side by side, six sides of an object, or one view under four passes, in a single image. Every cell reports 'luma': the tone of the pixels it encoded, in code values on the 0-255 scale: min/max/mean, the percentiles p1 p5 p50 p95 p99, 'span' (max-min), 'spread' (p95-p5), and 'crushed'/'clipped', the shares sitting at 0 and at 255. Read 'spread' to answer whether a shot is legible: a subject can be modelled, lit and drawn and still arrive inside a handful of code values, which a mean cannot tell from a picture with something in it. A capture is taken whenever the engine reaches it rather than at the instant the call was sent, and the world keeps running between calls, so two shots of a running scene are separated by the real seconds between them; pause it or slow it when the picture has to catch a specific moment.
| Name | Required | Description | Default |
|---|---|---|---|
| as | No | Your own name, when you are one of several agents sharing one connection to this engine (the sub-agents one agent session runs share its connection, so without it the engine sees all of them as one caller). Pass the same name on every call you make. The engine then treats you as a caller of your own: your roster name is this name, and your play session, the play-shadow writes and refusals that say who wrote what, engine.modeOwner, your shell session and your notices are yours alone. Lowercase letters, digits, '-' and '_'. Leave it out when you are the only agent on your connection. | |
| fov | No | Vertical field of view in degrees, stated for this capture alone. Omit to take the lens of whatever is being captured: a capture of a camera ('main', 'screen', 'viewport', 'editor', 'camera') renders at that camera's own fov, and one standing at a position or orbiting an entity renders at 60. | |
| grid | No | Collage layout as 'COLSxROWS' (e.g. '3x3', '2x2', '4x2'). Omit to have it worked out from the number of cells; a grid too small for them is an error rather than a silent crop. | |
| mode | No | 'image' = one frame. 'collage' = a GRID of frames in one image, where what varies from cell to cell is what you pass: 'setups' for a cell per whole camera set-up (the contact sheet of a shot list), 'viewpoints' for a cell per named view of one subject, 'passes' for a cell per render pass, or 'duration' for a cell per sample over time. Naming a station axis ('setups' or 'viewpoints') alongside 'passes' lays out a 2D grid (a row per station, a column per pass). A collage with no axis is an error naming all of them — it does not default to time. | image |
| pass | No | Which render output to produce. 'final' = normal lit rendering (default). The built-in debug passes replace the fragment output with a diagnostic buffer — use these to verify geometry and material correctness without reasoning about final lit pixels: 'normal' (alias 'world_normal') = per-pixel world-space normal (RGB = xyz*0.5+0.5), the geometry sanity check; 'normal_texture' = raw normal map sample before TBN (flat blue if no normal map); 'depth' (alias 'linear_depth') = distance from the camera on a log curve (near black, far white), the fastest way to read scene layout; 'albedo' / 'roughness' / 'metallic' / 'ao' / 'emissive' = the corresponding PBR channel, drawn magenta on a surface whose shader lights itself and hands the engine no material to read; 'tangent' = world-space tangent; 'material_flags' = R=normal_map, G=roughness_metallic_tex, B=base_color_tex; 'shadow' = the share of the direct light reaching each fragment that survived every shadow test, over EVERY light standing on it — sun, point, spot and area alike (white = all of it, black = none of it), so a fragment the 'final' pass renders dark for being shadowed reads dark here; 'shadow_depth' = the map behind that answer for the light putting the most light on the fragment — R = the depth the fragment carries in that light's map, G = the depth the map already held there, B = which light answered (0 the sun's cascades, 0.25 a parallel light, which claims a map of no kind, 0.5 a spot or area light's atlas tile, 1 a point light's cube face); 'motion_vectors' = the frame's velocity buffer — each pixel's screen-space travel between the previous frame and now, whichever pass wrote it (a material, the splat pass, a render feature naming @scene.motion); static pixels flat black, moving pixels colour-biased. Beyond these, `pass` also accepts the name of any CONTENT-registered capture view (a render feature that publishes a view — e.g. a baked-lightmap view); an unknown name is resolved against that registry and, if it matches no view, the error lists what is available. Any pass but `final` is drawn under `all !sky !ui !EditorUI !debug` with the post-process chain off, so the buffer comes back as the value it encodes rather than as a graded picture of it; `renderLayers` and `postProcessing` each state that differently. | final |
| angle | No | Orbit direction as [yaw, pitch] in degrees (default [0, 20]). Only the viewing angle — distance is still auto-fit from bounds unless you set 'distance'. source='entity' only. | |
| basis | No | Which axes a 'viewpoint' is measured against. 'local' = the SUBJECT's own axes: 'front' is the side it faces however it is turned, and the frame is fitted to its own extents rather than the world-axis box around them. 'world' = the world axes: 'front' is whatever faces world +Z. Required alongside 'viewpoint' when framing an entity, because for anything rotated the two are different pictures. Framing a position instead of an entity, both values mean the world axes. | |
| owner | No | The key the holds this capture takes are stated under. `deterministic` pins the per-frame clock and `clearAir` holds the air, and both are cells every agent driving this engine renders through, so an agent can take one exclusively for a key of its own. A capture stating that key is admitted under the standing hold and photographs what its owner set; a capture stating another key, or none, is refused while that hold stands. It is the same key `renderer.temporal.hold` and `renderer.atmospherics.hold` take as `owner`, and their `release` hands the cell back by. | |
| width | No | Output width in pixels (image) or the whole SHEET's width (collage). A collage cell is rendered at the box the grid divides out of the sheet, so a cell holds the same picture a single capture at that cell's own width/height holds, and each cell reports the pixels it was rendered at. Omit to take the size of whatever is being captured: a capture of a camera ('main', 'screen', 'viewport', 'editor', 'camera') renders at the viewport's own pixel size, and one standing at a position, orbiting an entity or painting a UI window renders 1024 wide. | |
| camera | No | (source='camera', or with no source) A camera entity ref/id to render from. Renders that camera's authored pose offscreen - use it to validate any specific camera (a security cam, a cutscene cam) regardless of which camera is on screen. | |
| entity | No | What to frame (source='entity'): an entity name or id, OR an array of names/ids to frame several at once. The camera AUTO-FITS to the union of their world-space bounds, so the subject is guaranteed fully in frame at ANY scale: a 1cm prop and a 100m building both fill the shot. Single or list, name or id; you cannot pick the wrong shape. Framing is not isolation: this FITS THE FRAME to the subject, it does not decide what is drawn in it, and anything else standing there is still rendered, and a scene's default player spawn sits at the world ORIGIN, exactly where a prop is usually built. Pass 'isolate' to draw the subject without the other geometry. If the framed shot comes back empty, the geometry/material is the problem, not the camera. A name more than one entity carries is refused, and the refusal names each of them with its id; every cell reports the entities it framed under 'subjects'. | |
| format | No | Output image format. 'jpeg' (default) is smaller. 'png' is lossless. Ignored for source='ui_window' (always PNG). | jpeg |
| frames | No | source='presented' / 'window' only: how many presented frames to take, 1-32 (default 1). More than one comes back as a grid in the order the frames were presented, and each cell reports its frame number, so a run of consecutive frames reads as rising numbers at real gameplay speed: the measure of TAA convergence, motion blur, flicker and exposure adaptation over time. | |
| height | No | Output height in pixels (image) or the whole SHEET's height (collage). A collage cell is rendered at the box the grid divides out of the sheet, so a cell holds the same picture a single capture at that cell's own width/height holds, and each cell reports the pixels it was rendered at. Omit to take the size of whatever is being captured: a capture of a camera ('main', 'screen', 'viewport', 'editor', 'camera') renders at the viewport's own pixel size, and one standing at a position, orbiting an entity or painting a UI window renders 576 tall. | |
| lookAt | No | World point the camera aims at [x, y, z]. source='position' only; defaults to origin. | |
| passes | No | Collage pass axis: a cell per render pass, taking the same names as 'pass' (including content-registered capture views). One frame under final, albedo, normal and depth side by side is how a material problem separates from a geometry one. Combine with 'setups' or 'viewpoints' for a 2D grid. | |
| screen | No | (source='ui_window') Screen id passed to ui.registerScreen that contains the target Window. | |
| setups | No | Collage set-up axis: a cell per WHOLE camera set-up — the contact sheet of a shot list. Each entry takes the same options that aim a single capture ('source', 'camera', 'entity'/'entities', 'position', 'lookAt', 'rotation', 'distance', 'angle', 'margin', 'viewpoint', 'basis', 'projection', 'orthoHeight', 'fov', 'near', 'far', 'isolate'), plus 'label' to name the shot on the result; a field an entry leaves out is taken from the collage's own options, so a shot list writes down only what makes each shot differ. This is the axis for comparing several DIFFERENT stations and lenses of one scene at one instant — 'viewpoints' orbits one subject, 'duration' samples one camera over time. Exclusive with 'viewpoints' (both say where the camera stands); combine with 'passes' for a 2D grid, a row per set-up. | |
| source | No | Where the image comes from. 'presented' and 'window' READ the frame the engine presented; every other source RENDERS a frame of its own offscreen. 'presented' = the game view exactly as it was presented to the player, after the post chain, the upscale, the display transform and the UI, at the size it was composed at: the one source whose temporal antialiasing, motion blur, camera motion, auto exposure and render scale are the real ones, since nothing is re-rendered for it. 'window' = the whole presented window (or headless framebuffer) with the editor chrome and everything painted on the window. Both take 'frames' + 'interval' for a run of consecutive presented frames, report each frame's frame number, render scale, raster and composite sizes, projection jitter, exposure and history reset, and refuse the options that aim or shape a rendered frame (camera, entity, position, viewpoint, fov, pass, renderLayers, postProcessing). DEFAULT (omit, or 'main') = the MAIN SCENE CAMERA (the gameplay/PlayerPrototype camera or an agent-placed scene camera), rendered offscreen from its authored pose; it works in edit mode too (before you press play). Errors if the scene has no non-editor camera. 'editor' = the editor fly-camera you author with. 'screen' = a reproduction of the on-screen image, rendered offscreen from the camera holding the viewport under the render layers and diagnostic pass THAT camera draws the screen with, so a camera sitting on a diagnostic channel comes back as that diagnostic; the frame as presented is 'presented'. Passing 'renderLayers' or 'pass' alongside it states them for this capture instead. 'viewport' and 'gameplay' = aliases for the default (the scene camera). Pass 'camera' with a camera entity ref to render from any specific camera. 'entity' = orbit an ephemeral camera around an entity (entity + distance + angle). 'position' = render at an explicit world point (position + lookAt). 'ui_window' = render ONE egui Window into its own texture (screen + window). If 'source' is omitted: 'entity' when you pass 'entity', 'position' when you pass 'position', 'ui_window' when you pass both 'screen' and 'window', 'camera' when you pass 'camera', otherwise the main scene camera. | |
| window | No | (source='ui_window') Widget id of the Window inside that screen (e.g. 'system-tools-window'). | |
| isolate | No | Draw the subject WITHOUT the other geometry (source='entity' only). It changes exactly that: lighting, sky and post-process are untouched, so a final frame stays final — for a flat read of the geometry use 'pass'. Excluded geometry still casts shadows onto the subject and still bounces light into it, the same as any render-layer exclusion. The subject's layers are restored afterwards. In a 'setups' collage each cell shows its own set-up's subject alone; a set-up states 'isolate' of its own to override this for its cell. | |
| quality | No | JPEG quality 1-100 (format='jpeg' only). | |
| clearAir | No | How much of the air between the camera and a surface reaches this one frame. `true` takes it out entirely, so a surface renders in its own colour and its albedo, tint or material can be judged while another slice of a shared world drives the weather — a wash that no other option reaches, because aerial perspective and the volumetric media are render features rather than post-process or a render layer, so neither `postProcessing` nor `renderLayers` strips them. A number in [0, 1] keeps that share of the air instead. It reaches aerial perspective, height fog and volumetric light scattering wherever those are driven from, a component re-pushing them every frame included. The sky, the sun and the light they put on the surface are untouched, because those are what the surface's colour is made of, and the cloud layer and a placed volume draw as geometry that `renderLayers` and `isolate` already name. Scoped to this capture: the scene's own air is back the moment it returns, so a world several sessions share is never left in scratch weather. | |
| distance | No | Override the orbit distance (source='entity'). OMIT to auto-fit from world bounds (recommended — that's the guarantee that the subject is framed). Pass a value only to force a specific radius, which can push the subject out of frame. | |
| duration | No | Collage time axis: a cell per sample, spread across this many seconds of gameplay. Exclusive with 'setups', 'viewpoints' and 'passes' — a cell differing both in what it looks at and in when it was taken answers neither question. | |
| interval | No | source='presented' / 'window' only: how many presented frames apart two taken frames stand, 1-600 (default 1: consecutive frames). | |
| position | No | Explicit camera world position [x, y, z] (required when source='position'). | |
| save_path | No | Optional path to save the image to. Takes a VFS path in either spelling ('/source/tmp/shot.png' or '/zero/source/tmp/shot.png'), or a host-filesystem path ('/tmp/shot.png'). The image is still returned as base64 either way; the response reports 'savedTo' with the resolved destination, or 'saveError' explaining why there is no file. A VFS save is written without firing write side effects, so the file stays at the path 'savedTo' names and reads back from it: hand that path straight to 'set_world_cover', 'read_file' or 'vfs.read'. A VFS save under /zero/source made while play is running lands on the play shadow: the response then carries durable=false, a 'warning' naming the file a guarded play-exit deletes unless it is kept, and 'playShadow' naming the ways to keep it; a host-filesystem path is outside the VFS and is kept whatever play does. To make the image an imported texture asset instead, write it with 'write_file' or run the importer on it. | |
| viewpoint | No | A named camera station, instead of working out an 'angle'. front/back/left/right/top/bottom are the six sides; 'iso' is the corner view where all three axes project equally. REQUIRES 'basis' when framing an entity. Pair with projection='orthographic' to read a side as a true elevation. | |
| projection | No | 'perspective' (default) converges with distance, the way an eye sees. 'orthographic' covers a fixed world-space height at EVERY distance, so parallel edges stay parallel and two equal-size objects at different depths cover equal pixels — the projection to check a shape or compare sizes under, where perspective convergence hides both. | perspective |
| viewpoints | No | Collage view axis: a cell per named view of ONE subject. An array of viewpoint names, a space-separated string ('front top left'), or 'sides' for all six. Combine with 'passes' for a 2D grid; use 'setups' instead to vary the whole camera set-up from cell to cell. Exclusive with 'setups'. | |
| orthoHeight | No | World-space vertical extent an orthographic frame covers. Omit to fit it to whatever is being framed (recommended, the same way distance is auto-fit). | |
| renderLayers | No | Which render layers this capture includes — the control over both which objects draw and which passes run (sky/ui/EditorUI are built-in layers). Space-separated tokens: `all` seeds every layer, `name` adds a layer, `!name` drops one — e.g. `all !ui` for a clean shot with no UI overlay, `all !sky !ui` for a flat diagnostic background, or `default enemy` to render only those two layers. Post-processing is not a layer: pass `postProcessing = false` to capture the ungraded frame. Defaults omit `EditorUI` (the human editor's chrome) and `debug` (the debug-visualisation overlays — gizmos, light/probe icons, frustums, collider and bounds wireframes, several of which are on by default in edit mode) so agent captures aren't cluttered with them; pass `all` to include them. Naming a `pass` other than `final` states a stronger default than any of these: a diagnostic buffer's RGB is the reading, so that capture is drawn under `all !sky !ui !EditorUI !debug` and with the post-process chain off — the sky would paint its own colour where the buffer holds none, and the chain would grade the values being read. Stating `renderLayers` here replaces that spec, and `postProcessing = true` puts the chain back. Content `ui` is answered three different ways, by what aimed the shot. A capture of a camera the scene already holds — `main`/`viewport`/`gameplay` (the scene camera) and `editor` (the fly-cam) — keeps it, so an authored HUD is in the frame. A capture that BUILDS a camera to frame a subject — `entity` and `position` — drops it alongside the authoring layers, since a HUD drawn across the whole frame is unrelated to the subject being framed; pass `all !EditorUI !debug` to keep the HUD in a framed shot. Two sources answer from the camera they mirror rather than from either default: `screen` renders under the spec the on-screen camera draws the viewport with, verbatim, and `camera` under that named camera's own spec with the authoring overlays off, so each holds content `ui` exactly when the spec it mirrors does. `ui_window` paints one Window into a target of its own, and no render-layer spec applies to it. `presented` and `window` read the frame the engine presented, drawn under the layers the viewport camera draws with, and refuse a spec of their own. Overriding here scopes to THIS capture, unlike `debug.set`, which mutates the engine-wide state every other viewer shares. | |
| deterministic | No | Pin the clock every per-frame field is drawn against for the length of this capture. Film grain, an animated noise field and a jittered raymarch offset are redrawn each frame from that clock, so two shots of a scene in which nothing has moved otherwise differ over a large part of the frame — and a difference image cannot then answer whether anything in the shot moved. Pinned, they are redrawn identically, and every capture that asks for it pins at the same instant, so shots taken minutes apart still agree. It does not pin an accumulating temporal effect (TAA history, denoiser accumulation, auto-exposure adaptation), which settles by itself on a still scene. | |
| postProcessing | No | Whether this capture runs the post-process chain. Omitted, a capture naming a diagnostic `pass` drops the chain so its buffer is read flat, a capture from a specific camera mirrors that camera's own `postProcessing`, and every other capture keeps the chain, so a final frame stays a final frame. Pass false to read the scene ungraded: the chain comes off, and so does the film a render feature draws — the lens flare and grain, the bokeh a short focus throws, the shutter's smear — each declared part of the camera's photographic finish by the pass that draws it, so a graded frame and an ungraded one are different pictures. Post-processing is a Camera property, not a render layer, so `renderLayers` cannot strip it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/destructive/openWorld, and the description goes well beyond them: it discloses that a capture is taken when the engine reaches it rather than at call time, that the world keeps running between calls, that isolate does not strip shadows/bounce light, that clearAir is scoped to the capture, and that deterministic pins the frame clock. These are real behavioral traits an agent cannot get from the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The verb and scope are front-loaded, which is good, but the four dense paragraphs contain long run-on clauses and some duplication of schema text (e.g. the repeated size/default rules). Much of it earns its place given the 35-parameter surface, but the luma-metric digression and nested parentheticals make it heavier than it needs to be.
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 35-parameter tool with no output schema, the description is unusually complete: it covers all sources, the auto-resolution of source and size, collage axes, render-layer defaults, post-processing interaction, isolation semantics and save side effects. An agent has enough to select and invoke correctly without further probing.
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 already 100%, so the baseline is 3. The description earns a step above by adding interpretive meaning the schema does not carry — the luma report fields (min/max/mean, percentiles, span, spread, crushed/clipped) and how to read 'spread' to judge legibility, plus the default-resolution rule for source. The remaining param-level text largely restates the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states a specific verb and resource ('Render an image or collage from the engine, or read the frame it presented') and immediately distinguishes the two read sources ('presented' vs 'window') from rendered ones. No sibling tool covers capture, and an agent can tell this apart from set_world_cover, preview or zeromind.preview without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It routes explicitly: 'Pick WHERE with source', 'WHAT with pass', 'HOW it projects with projection', and it names when to reach for motion_vectors or normal passes. It also gives the alternative path for a different outcome ('To make the image an imported texture asset instead, write it with write_file') and timing advice (pause the world when a specific moment matters).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full schema for one registered tool — its arguments, types and behaviour. Use after search_tools locates it and before calling it, instead of guessing arguments. Answered by the attached engine, so it needs one: world.open attaches one.
| Name | Required | Description | Default |
|---|---|---|---|
| as | No | Your own name, when you are one of several agents sharing one connection to this engine (the sub-agents one agent session runs share its connection, so without it the engine sees all of them as one caller). Pass the same name on every call you make. The engine then treats you as a caller of your own: your roster name is this name, and your play session, the play-shadow writes and refusals that say who wrote what, engine.modeOwner, your shell session and your notices are yours alone. Lowercase letters, digits, '-' and '_'. Leave it out when you are the only agent on your connection. | |
| tool | Yes | Tool name. | |
| toolbox | No | Toolbox that owns it, when the name is ambiguous. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds value beyond that by disclosing the external dependency — the call is 'answered by the attached engine' and fails without one, with world.open as the remedy. It stops short of describing the returned schema shape, but the tool's whole output is 'a full schema' and no output schema is declared.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three compact sentences, front-loaded with the purpose and then the workflow position. The engine-prerequisite sentence is slightly compressed to the point of being terse, but every sentence carries distinct information and nothing is repeated.
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 read-only introspection tool with one required parameter, full schema coverage and no output schema, the description covers what the tool returns, when to call it, and the operational prerequisite. The only gap is that it doesn't explain how ambiguous tool names are resolved across toolboxes, which the schema's `toolbox` parameter hints at but does not connect back.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the `as` parameter in particular carries a long, self-sufficient description, so the baseline is 3. The tool description adds no per-parameter detail — it only reinforces that the whole point is to learn arguments, which duplicates the schema rather than extending it.
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: 'Full schema for one registered tool — its arguments, types and behaviour.' It also implicitly distinguishes itself from the sibling search_tools by positioning itself as the schema-fetch step. An agent can tell it apart from adjacent tools like use_tool or search_tools 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?
Gives explicit sequencing: 'Use after search_tools locates it and before calling it.' It also names the alternative behaviour being avoided ('instead of guessing arguments') and states the prerequisite ('it needs [an attached engine]: world.open attaches one'). This is a genuine when/when-not with the enabling condition spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Flip the connected world back into EDIT mode: gameplay pauses, /zero writes unlock. Returns the resulting run-state. This is the mode flip — to change a file, use edit_file.
| Name | Required | Description | Default |
|---|---|---|---|
| as | No | Your own name, when you are one of several agents sharing one connection to this engine (the sub-agents one agent session runs share its connection, so without it the engine sees all of them as one caller). Pass the same name on every call you make. The engine then treats you as a caller of your own: your roster name is this name, and your play session, the play-shadow writes and refusals that say who wrote what, engine.modeOwner, your shell session and your notices are yours alone. Lowercase letters, digits, '-' and '_'. Leave it out when you are the only agent on your connection. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false, so safety is largely covered. The description adds genuine context beyond that: gameplay pauses and /zero writes become available, and it notes a run-state is returned. It does not say what happens to concurrent play sessions or to a repeated flip, leaving a small gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences: effect first, then state change, then routing to the alternative. Every sentence earns its place with no padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter mode-flip tool, the description covers purpose, side effects, and sibling routing. There is no output schema, and it mentions only that a run-state is returned without describing that shape, plus it is silent on interaction with already-running play sessions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the `as` parameter is documented exhaustively in the schema (shared-connection caller identity). The description adds no additional parameter meaning, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource — 'Flip the connected world back into EDIT mode' — with concrete effects (gameplay pauses, /zero writes unlock). It explicitly distinguishes itself from the sibling edit_file, so an agent can route 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit routing: 'This is the mode flip — to change a file, use `edit_file`.' It names the alternative and the condition that selects it, leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace an exact string in a world VFS file.
| Name | Required | Description | Default |
|---|---|---|---|
| as | No | Your own name, when you are one of several agents sharing one connection to this engine (the sub-agents one agent session runs share its connection, so without it the engine sees all of them as one caller). Pass the same name on every call you make. The engine then treats you as a caller of your own: your roster name is this name, and your play session, the play-shadow writes and refusals that say who wrote what, engine.modeOwner, your shell session and your notices are yours alone. Lowercase letters, digits, '-' and '_'. Leave it out when you are the only agent on your connection. | |
| new | No | Alias for new_string | |
| old | No | Alias for old_string | |
| path | Yes | ||
| quiet | No | When true, write the result without firing write side effects (importer dispatch, assetType onChange, vfs.watch subscribers). | |
| durable | No | When true, the edited bytes go to canonical /source even while play is RUNNING, and the session stays in play. The affected modules and components hot-reload, so the edit is observed running in the same play session with nothing left to promote — the call for bytes whose destination is known before they are edited, where vfs.promotePlayShadow(path or {paths}) takes bytes already on the shadow with play still running. An edit that cannot become canonical source is an error naming why, instead of a success that landed on the shadow. | |
| new_string | No | ||
| old_string | No | ||
| replace_all | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, and the one-line description adds nothing beyond them. It does not disclose what happens on a failed/ambiguous match, whether the write touches canonical source or a shadow, or the error behavior that the sibling parameters hint at.
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 wasted words. It is efficient, though arguably too terse for a 9-parameter tool with alias semantics.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, non-idempotent mutation tool with 9 parameters, alias pairs, and no output schema, a one-line description is inadequate. It omits usage context, the meaning of the no-op behaviors, and any guidance on matching or promotion semantics that the schema only partially covers.
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 a middling 56%: 'as', 'quiet', and 'durable' carry rich descriptions, but 'path', 'new_string', 'old_string', and 'replace_all' are undocumented. The description supplies no parameter meaning at all (no mention of aliases, replace_all, or required fields), so it does not compensate for the gaps.
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?
"Replace an exact string in a world VFS file" gives a specific verb (replace) and resource (an exact string within a VFS file), which is more precise than a generic edit. It does not, however, differentiate from close siblings like write_file, edit, or edit_world_metadata.
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 statement of when to use this tool versus alternatives such as write_file or edit, nor any prerequisites (e.g., that the file must exist or that the old string must match exactly once). The exact-string-match nature is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the connected world's face — title, description, README body, tags — and who can open it. A world nobody can recognise or search for is hard to find even when it is public.
| Name | Required | Description | Default |
|---|---|---|---|
| as | No | Your own name, when you are one of several agents sharing one connection to this engine (the sub-agents one agent session runs share its connection, so without it the engine sees all of them as one caller). Pass the same name on every call you make. The engine then treats you as a caller of your own: your roster name is this name, and your play session, the play-shadow writes and refusals that say who wrote what, engine.modeOwner, your shell session and your notices are yours alone. Lowercase letters, digits, '-' and '_'. Leave it out when you are the only agent on your connection. | |
| body | No | README body (markdown). | |
| tags | No | ||
| title | No | ||
| topics | No | Free-form topics. | |
| category | No | Curated category slug. | |
| visibility | No | Who can open the world NOW. public: anyone, and it is listed. unlisted: anyone with the link, not listed. private: only the owner, members and admins. On a draft, public or unlisted takes it out of draft to that (the same as world.undraft); private leaves the draft as it is. Visibility decides who can open the page; pushing commits is what gives visitors something to play. | |
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is partly covered. The description adds only the motivation for good metadata; it does not disclose whether unspecified fields are preserved or wiped, whether it's a partial upsert, or what permissions are required — notable gaps for a destructive setter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the field list. The second sentence is motivational framing rather than operational detail; it is short but only partly earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter, destructive, no-output-schema mutation tool, the description covers the primary fields but omits update semantics (partial vs replace), return behavior, and permission requirements. Annotations carry part of the load, leaving this adequate but with clear gaps.
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?
At 63% schema coverage the schema already documents most fields well, including the elaborate 'as' multi-agent attribution and the 'visibility' semantics. The description names four of eight fields but adds no syntax, format, or meaning beyond what the schema provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Set') and enumerates the resource's editable fields (title, description, README body, tags, and via 'who can open it', visibility). An agent can tell it apart from media/cover siblings like set_world_cover and world.set_media, though the metaphorical 'face' phrasing is slightly imprecise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance. It does not tell the agent when to prefer this over world.undraft (which the schema notes does the same draft-exit for public/unlisted), nor what preconditions exist. Only the closing sentence hints at a motivation (discoverability), not a selection rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run Luau code in the connected world and return its result, logs, and engine state. Long runs are promoted to a background task ({status:"running", taskId, hint}); the hint says what to do next for your harness (wait resumes the task).
| Name | Required | Description | Default |
|---|---|---|---|
| as | No | Your own name, when you are one of several agents sharing one connection to this engine (the sub-agents one agent session runs share its connection, so without it the engine sees all of them as one caller). Pass the same name on every call you make. The engine then treats you as a caller of your own: your roster name is this name, and your play session, the play-shadow writes and refusals that say who wrote what, engine.modeOwner, your shell session and your notices are yours alone. Lowercase letters, digits, '-' and '_'. Leave it out when you are the only agent on your connection. | |
| args | No | Values injected as the SCRIPT_ARGS global. | |
| code | No | Inline Luau source to run. | |
| file | No | VFS path to a .luau file to run instead of `code`. | |
| logs | No | Minimum log level to return (default error). | |
| strict | No | Per-call override for the LSP strict gate. Defaults to true (honour the world's lsp.strict_mode). Set to false on a single call to skip the gate even when error-level diagnostics are present — useful when prototyping against runtime-installed globals the LSP can't see. Diagnostics still flow back in the result so you see what was bypassed. | |
| logScope | No | Whose work the engine-window log lines in the response may be about (default: caller). One engine serves several agents at once and runs all of their content, so its log holds all of their failures. `logs` says how severe a line must be to appear; this says whose work it may be about, which no severity floor can express, because a neighbour's per-frame error IS an error. `caller` keeps the lines this call's own work raised plus the engine's own, and closes the list with one <n error lines from another caller's work left out> marker when there were any. `all` keeps every caller's, which is what a reader debugging the whole engine wants. The engine's own subsystem lines carry no caller and are kept either way. | |
| wait_frames | No | Frames to await deferred work (default 4). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the risk profile is covered. The description adds genuinely new behavior the annotations cannot express: long runs are promoted to a background task and the response shape becomes {status:"running", taskId, hint}. It still does not state permission requirements or what state the code can mutate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action and return values before the async caveat. The second sentence packs a lot into one clause with an embedded response literal, but nothing is wasted or redundant.
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?
No output schema exists, so the description must describe returns, and it does: result, logs, engine state, plus the discriminated running-task shape. For an 8-parameter arbitrary-code tool the picture is nearly complete, with only error/failure shape and environment prerequisites left implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the schema prose for `as` and `logScope` is far richer than anything in the description, so the schema does the heavy lifting and the baseline is 3. The description contributes only the response-side `hint`/`taskId` shape, nothing that clarifies a parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb + resource: 'Run Luau code in the connected world', plus what it returns (result, logs, engine state). The Luau-in-world framing implicitly separates it from the `bash` sibling, but no sibling is ever named, so an agent must infer the boundary itself.
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?
Goes beyond stating purpose by explaining the long-run path: runs that exceed a threshold become background tasks, and the returned `hint` tells the harness what to do next, with `wait` named as the resume mechanism. That is real routing guidance, though there is no explicit when-not-to-use or guidance on choosing this over `bash`.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search or read the engine's built-in guides (API topics, how-tos, and each asset type's README under types/). list enumerates every guide path, path reads one, query searches them. Works with or without an engine. With one attached, that engine answers, by meaning, and also reaches the world's own guides and its installed libraries. With none, the answer comes from the published Zero docs, matched by keyword, and says so: served_by is "docs" and engine says why no engine answered.
| Name | Required | Description | Default |
|---|---|---|---|
| as | No | Your own name, when you are one of several agents sharing one connection to this engine (the sub-agents one agent session runs share its connection, so without it the engine sees all of them as one caller). Pass the same name on every call you make. The engine then treats you as a caller of your own: your roster name is this name, and your play session, the play-shadow writes and refusals that say who wrote what, engine.modeOwner, your shell session and your notices are yours alone. Lowercase letters, digits, '-' and '_'. Leave it out when you are the only agent on your connection. | |
| from | No | WHERE results may come from. 'all' (default) is everything published. 'bound' is the current world and its installed libraries, answered by this engine with no published-library leg; `mode` still picks how the query is matched, and mode='keyword' reads this engine's own files, unpushed ones and a private world's included. | |
| list | No | Enumerate all guide paths. `path` and `query` are ignored. | |
| mode | No | semantic finds content by what you are trying to do; keyword matches the words in the files each type declares — a README, a guide body, code. Default: semantic on a live engine, keyword offline. An attached engine reads it; the answer from the published docs does not. | |
| path | No | Guide identity, e.g. topics/physics or types/shader. A short form (physics) works when only one guide answers to it. With `query`, narrows the search to the guides under this identity. | |
| tier | No | How much of each entry the guide index (no `path`, no `query`) returns: 1 the paths alone, 2 adds each guide's kind and summary, 3 adds the file behind it and the other spellings it answers to. An attached engine reads it; the answer from the published docs does not. | |
| limit | No | Max matches to return when searching. An attached engine reads it; the answer from the published docs does not. | |
| match | No | What a hit must match: what a thing IS, its README (identity); what it DOES and how it is made, a guide body or code (capability); either (any, default); both (all). Applies to keyword mode only; semantic ranking does not read it. An attached engine reads it; the answer from the published docs does not. | |
| query | No | What you are looking for, in plain words. | |
| assetType | No | Comma-separated documentation types a `query` searches: 'guide', 'agentskill', 'assettype', 'guide,assettype'. Omit to search all three. Any other type is refused: `search_tools` searches tools and toolboxes, and `zeromind.search` every other kind. An attached engine reads it; the answer from the published docs does not. | |
| context_lines | No | Lines of surrounding context above and below each matched line in the snippets a `path` + `query` scan returns. An attached engine reads it; the answer from the published docs does not. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/openWorld/non-destructive, and the description adds real context beyond them: the degraded offline path served by published Zero docs, the returned `served_by` value of 'docs', and the `engine` field explaining why no engine answered. This is exactly the kind of fallback disclosure an agent needs.
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 dense paragraph that is front-loaded with the core action and the list/path/query mapping before the engine-vs-offline nuance. It is long but nearly every clause carries routing or fallback information; only minor compression is possible.
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 11 optional parameters and no output schema, the description covers the critical axis (online vs. offline behavior and the `served_by`/`engine` response fields) and defers per-parameter detail to the rich schema. It stops short of describing the shape of a `query` result set, but the schema's tier/match descriptions fill most of that gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so every parameter already carries a detailed description including the 'attached engine reads it; published docs does not' caveat. The prose largely restates the schema (mode defaults, tier meaning) without adding format or syntax beyond it, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Search or read the engine's built-in guides') and immediately scopes the content (API topics, how-tos, types/<name> READMEs). The three sub-operations (list/path/query) are named so an agent can distinguish them without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes to alternatives: 'search_tools searches tools and toolboxes, and zeromind.search every other kind', and it distinguishes behavior with vs. without an attached engine. The mode selection (semantic default on a live engine, keyword offline) is spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Freeze or resume the world WITHOUT leaving the current mode — how you hold a moving scene still for a clean capture. Returns the resulting run-state.
| Name | Required | Description | Default |
|---|---|---|---|
| as | No | Your own name, when you are one of several agents sharing one connection to this engine (the sub-agents one agent session runs share its connection, so without it the engine sees all of them as one caller). Pass the same name on every call you make. The engine then treats you as a caller of your own: your roster name is this name, and your play session, the play-shadow writes and refusals that say who wrote what, engine.modeOwner, your shell session and your notices are yours alone. Lowercase letters, digits, '-' and '_'. Leave it out when you are the only agent on your connection. | |
| paused | No | true to freeze, false to resume. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true). The description adds genuinely useful context beyond them: that the operation preserves the current mode and that it returns the resulting run-state. It doesn't detail side effects or permissions, but with annotations carrying that burden this is solid added value.
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 tight sentence front-loads the core action, embeds the key constraint, and a short second sentence states the return. No waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-param, zero-required toggle with annotations already covering safety, the description covers purpose, the mode-preservation nuance, and the return value. Slightly thin on when-not-to-use guidance, but complete enough to invoke 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 100%, including a detailed `as` description covering multi-agent addressing. The description adds no parameter-level detail beyond the schema, so the baseline 3 for high coverage applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb pair (freeze/resume) and resource (the world), and adds a distinguishing constraint ('WITHOUT leaving the current mode') that separates it from mode-switching siblings. An agent can tell this is a non-destructive state toggle rather than a general 'play' or 'capture' action.
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?
Gives clear usage context — this is 'how you hold a moving scene still for a clean capture' — routing the agent to pair it with `capture`. It stops short of stating when-not to use it or naming explicit alternatives, so it's clear context without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Flip the connected world into PLAY mode: scripts tick, physics simulates, /zero writes lock. Returns the resulting run-state. Refused while user content under /zero/source has error-severity diagnostics — the refusal names them; fix those rather than working around it.
| Name | Required | Description | Default |
|---|---|---|---|
| as | No | Your own name, when you are one of several agents sharing one connection to this engine (the sub-agents one agent session runs share its connection, so without it the engine sees all of them as one caller). Pass the same name on every call you make. The engine then treats you as a caller of your own: your roster name is this name, and your play session, the play-shadow writes and refusals that say who wrote what, engine.modeOwner, your shell session and your notices are yours alone. Lowercase letters, digits, '-' and '_'. Leave it out when you are the only agent on your connection. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare the safety profile (not read-only, open-world, not idempotent, not destructive); the description adds substantive behavior beyond that — what entering PLAY mode actually does to scripts, physics, and write locking, that it returns the resulting run-state, and that calls are refused under a named diagnostic condition. The refusal path and its error-surfacing behavior are unusual and genuinely useful disclosures that annotations cannot convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three front-loaded sentences with no filler: the action and its effects lead, the return value follows, and the failure condition closes. Each sentence carries distinct information an agent needs.
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 annotations covering safety and the schema covering the one parameter, the description supplies the remaining essentials: effects, return shape, and refusal semantics. It stops short of describing what the run-state contains or how re-entry while already in PLAY behaves, but no output schema exists that would otherwise carry that burden.
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?
There is a single optional parameter (`as`) and the schema description already documents it at full coverage, including naming conventions and multiplicity semantics. The description says nothing about it, so per the high-coverage baseline it neither compensates nor detracts.
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 concrete action and target state ("Flip the connected world into PLAY mode") and enumerates the observable consequences — scripts tick, physics simulates, `/zero` writes lock — which is far more specific than a bare mode switch. It does not explicitly name its obvious counterpart `pause`, so differentiation from the sibling is left to inference from the mode name rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states a clear precondition and the prescribed remedy: refused while error-severity diagnostics exist under `/zero/source`, and the agent should fix those rather than work around the refusal. What's missing is the symmetric guidance — when to call `pause` instead, or what happens if the world is already in PLAY, so the alternative route is never spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render a preview image of an asset without spawning it into the scene.
| Name | Required | Description | Default |
|---|---|---|---|
| as | No | Your own name, when you are one of several agents sharing one connection to this engine (the sub-agents one agent session runs share its connection, so without it the engine sees all of them as one caller). Pass the same name on every call you make. The engine then treats you as a caller of your own: your roster name is this name, and your play session, the play-shadow writes and refusals that say who wrote what, engine.modeOwner, your shell session and your notices are yours alone. Lowercase letters, digits, '-' and '_'. Leave it out when you are the only agent on your connection. | |
| asset | Yes | Asset identity to render. | |
| width | No | ||
| height | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, and the phrase 'without spawning it into the scene' is consistent with that safety profile, adding useful confirmation that no scene mutation occurs. However, it says nothing about what is returned (image bytes, URL, format) or whether rendering has cost/latency implications, which it could given no output schema exists.
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 tight sentence with zero filler, leading with the action and ending with the key constraint. Efficient and well front-loaded, though the terseness is also what leaves parameters and output unaddressed.
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 four-parameter rendering tool with no output schema, an agent still doesn't know how the preview is delivered (inline image, file path, URL) or what width/height mean. The core purpose is clear, but the description is not complete enough for confident invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%: 'as' is heavily documented in-schema, but 'width' and 'height' have no descriptions at all, and the tool description never mentions them or the 'asset' argument. Units, defaults, and aspect behavior for width/height are left entirely undocumented, so the description fails to compensate for the coverage gap.
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 (Render), a concrete resource (preview image of an asset), and a scope qualifier (without spawning it into the scene). The qualifier implicitly distinguishes it from spawn/play siblings like 'play', though no sibling is named 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?
Usage is only implied: use this when you want to inspect an asset visually without adding it to the scene. There is no explicit when-to-use framing, no prerequisites, and no named alternative for the case where the agent does want to instance the asset.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a file from the world VFS. Returns text, an image (for PNGs), or a directory listing.
| Name | Required | Description | Default |
|---|---|---|---|
| as | No | Your own name, when you are one of several agents sharing one connection to this engine (the sub-agents one agent session runs share its connection, so without it the engine sees all of them as one caller). Pass the same name on every call you make. The engine then treats you as a caller of your own: your roster name is this name, and your play session, the play-shadow writes and refusals that say who wrote what, engine.modeOwner, your shell session and your notices are yours alone. Lowercase letters, digits, '-' and '_'. Leave it out when you are the only agent on your connection. | |
| path | Yes | VFS path, e.g. /scene/main.luau | |
| limit | No | Maximum number of lines to return, counting from `offset` (defaults to line 1). Text files only — ignored for images. | |
| offset | No | 1-based line number to start reading from. Text files only — ignored for images. When set without `limit`, reads up to 2000 lines from there. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, non-destructive, openWorld), so the bar is lower. The description usefully adds that return type varies by file type — text, PNG image, or directory listing — which is genuine behavioral context an agent cannot get from the annotations.
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 tight sentences with the primary action front-loaded and return behavior immediately after. No wasted words, though it is minimal rather than optimally structured.
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 read tool with full schema coverage and no output schema, briefly noting the possible return shapes (text, image, listing) covers the key gap. Pagination and the shared-connection `as` semantics live in the schema, so little 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 100%, so the schema already documents path, as, limit and offset thoroughly. The description adds no parameter meaning beyond what the schema provides, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Read a file from the world VFS') and clarifies the three return shapes (text, image, directory listing). It is clearly distinct from write_file/edit_file siblings, though it does not name them 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?
No explicit when-to-use or when-not guidance and no named alternatives; the usage is only implied by the read nature of the tool. An agent can infer it is for reading, but nothing routes it against similar readers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the Zero tool registry. Tools are named, typed operations grouped into toolboxes (entityOps, scene, appearance, lighting, …). With no arguments, returns the toolbox overview — one row per toolbox with its purpose and tool count. toolbox returns all of that toolbox's tools; query on its own searches every tool and toolbox this world can reach — its own, the builtin library, installed libraries and imports — by meaning (mode: "semantic") or by words (mode: "keyword"), and answers the top 25 compact rows: the callable identity, whether the hit is a tool or a toolbox (drill into a toolbox with toolbox), and a one-line purpose. The answer names the mode and slot that ran, the worlds it covered, and its status. A query given with a toolbox searches inside that toolbox's registered tools instead. Pass schema: true on a toolbox drill-in for full signatures, args, and examples inline, or call describe_tool for one tool's full schema. Run a result with tool_exec. Answered by the attached engine, so it needs one: world.open attaches one. guides answers without an engine.
| Name | Required | Description | Default |
|---|---|---|---|
| as | No | Your own name, when you are one of several agents sharing one connection to this engine (the sub-agents one agent session runs share its connection, so without it the engine sees all of them as one caller). Pass the same name on every call you make. The engine then treats you as a caller of your own: your roster name is this name, and your play session, the play-shadow writes and refusals that say who wrote what, engine.modeOwner, your shell session and your notices are yours alone. Lowercase letters, digits, '-' and '_'. Leave it out when you are the only agent on your connection. | |
| from | No | WHERE results may come from. 'all' (default) is everything published. 'bound' is the current world and its installed libraries, answered by this engine with no published-library leg; `mode` still picks how the query is matched, and mode='keyword' reads this engine's own files, unpushed ones and a private world's included. | |
| mode | No | semantic finds tools by what they do; keyword matches the words in each tool's README and code. Default: semantic on a live engine, keyword offline. | |
| limit | No | Optional cap on the number of results. On the `toolbox` drill-in it is a trim, not a ceiling — omit it to return EVERY tool, since compact rows stay small and a genuinely large listing spills to a retrievable file rather than being silently truncated. A query answers the top 25 ranked hits; a smaller limit trims them. | |
| match | No | What a hit must match: the README (identity), the code and its declared interface (capability), either (any, default), both (all). | |
| query | No | One phrase, as a string, naming what you are looking for in plain words. On its own it searches every tool and toolbox this world can reach (its own, the builtin library, installed libraries and imports) and answers compact rows. Given WITH a `toolbox` it instead matches the words of that toolbox's own registered tools, and `mode` / `match` do not apply. Omit (with no `toolbox`) to browse the TOOLBOX overview: one row per toolbox with its purpose and tool count. | |
| schema | No | Include each tool's full schema (signature, args, returns, examples) inline. Applies to the `toolbox` drill-in; a `query` answers compact rows — the callable identity plus a one-line purpose. Fetch one tool's full schema on demand with describe_tool. | |
| toolbox | No | Drill into one toolbox — return its tools (e.g. entityOps, camera, lighting, baking). Call with no arguments first for the list of toolbox names. With a `query`, the search runs over that toolbox's registered tools rather than over the content this world can reach. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/openWorld annotations, it discloses prerequisites (needs an attached engine; world.open attaches one), the shared-connection identity model for `as`, the fact that keyword mode reads unpushed private files, and that large listings spill to a retrievable file rather than being silently truncated. It also previews the answer's metadata (mode, slot, worlds covered, status).
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?
It is front-loaded with purpose and the overview behavior first, then branches to drill-in and query semantics. The prose is dense and some sentences carry multiple clauses, but nearly every sentence conveys a distinct behavior rather than filler.
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 8 parameters, zero required, and no output schema, the description carries the return-shape burden itself by describing the compact rows (callable identity, tool vs toolbox, one-line purpose) and the appended answer metadata. Prerequisite and mode-default behavior are covered, so an agent can call 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 coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema cannot: query alone searches everything reachable while query+toolbox scopes to that toolbox and nullifies mode/match, and limit is a trim on queries but not a ceiling on toolbox drill-ins. This relational context is genuinely additive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence names a specific verb and resource ('Search the Zero tool registry') and immediately explains the three operating shapes: no-argument toolbox overview, `toolbox` drill-in, and standalone `query`. It distinguishes itself from siblings by naming describe_tool for single-tool schemas and tool_exec for running results.
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?
Explicit routing is given: use `schema: true` on a toolbox drill-in or call describe_tool for one tool's schema, run hits with tool_exec, and note that `guides` answers without an engine. When-not conditions are stated (query with toolbox bypasses mode/match; keyword offline default), leaving little to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pin this conversation to ONE engine, so every later call (execute, capture, write_file, …) drives that same engine. Name it with session (from session.list), or describe it with world and, when the world has engines on more than one branch, branch. A branch is never chosen for you: engines on different branches have different working trees, so naming none where several exist is refused, listing them. Naming both session and a world (or branch) the engine is not on is refused, naming both, and pins nothing. Held, as world.connect is, only for an engine that is about to connect (its editor has drawn its first frame); otherwise answered at once with what the editor is doing. Naming a player is refused: open the world with world.open to get an editor to work in.
| Name | Required | Description | Default |
|---|---|---|---|
| guid | No | The same argument as `world`, under another name: give one of the two. A call giving them two different worlds is refused. | |
| world | No | World guid, when you are describing the engine rather than naming it. Beside `session` it has to be that engine's world, or the call is refused. A value that is not a guid, a world's name included, is refused. | |
| branch | No | Which branch's engine you mean. Required when the world has engines on more than one. | |
| session | No | Exact engine session id from session.list. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, idempotentHint=false, openWorldHint=true), the description discloses a genuinely non-obvious behavior: the call is 'Held... only for an engine that is about to connect (its editor has drawn its first frame); otherwise answered at once with what the editor is doing.' It also enumerates refused inputs. It does not explain persistence lifetime of the pin, which keeps it below 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core purpose is front-loaded, but the body is dense and several clauses are awkwardly constructed ('Naming both, and pins nothing', 'Held, as world.connect is'), making the refusal rules slower to parse than needed. Every clause carries information, but the packaging is not clean.
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 stateful, refusal-heavy connect tool with no output schema and full schema coverage, the description covers the main failure modes, the hold-vs-immediate-answer behavior, and the escape hatch (world.open for players). Only minor gaps remain, such as what the pin persists across or how to release it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is already 100%, so the baseline is 3, but the description adds cross-parameter decision logic the schema does not: 'session' names an engine exactly, `world`+`branch` describes it, `branch` is 'never chosen for you', and mixing `session` with a conflicting `world`/`branch` is refused. This frames the pick-one relationship between the four params rather than restating field types.
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 opening sentence states a concrete verb and resource: 'Pin this conversation to ONE engine, so every later call (execute, capture, write_file, …) drives that same engine.' That tells the agent what the tool does and why it matters. It references session.list and world.connect but never explicitly contrasts itself with world.open/world.disconnect siblings beyond the player-naming refusal, so sibling differentiation is partial.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description spells out explicit alternatives and conditions: name via `session` (from session.list) OR describe via `world`/`branch`, plus the exact refusal cases — naming no branch where several exist, naming both session and a conflicting world, and naming a player (redirected to world.open). When/when-not/alternative routing is all present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the engines you have running: which world and BRANCH each is bound to, whether it is a browser tab, a native engine or a player, and whether another conversation is already driving it. Call this when a tool tells you the target is ambiguous, or before session.connect, to see what there is to choose from. A player (drivable: false) is someone playing the world in the runtime profile: it takes no edits and keeps nothing when it exits, so it is listed for you to see and is never driven or bound.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description nonetheless adds real behavioral context by explaining the player state (drivable: false, takes no edits, keeps nothing when it exits, never driven or bound), which is not encoded in any structured field.
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-loaded with the verb and the returned fields, then the usage triggers. The third sentence on player semantics is longer than strictly necessary but carries non-obvious meaning, so it earns most of its space.
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?
There is no output schema, so the description carries the burden of explaining what is returned, and it does: the world, the branch, the engine kind, the driving conversation, and the player caveat. An agent has enough to call and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so schema coverage is moot and the baseline is 4. The description correctly implies the tool is unfiltered and takes no arguments, so there is nothing further to document.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("List the engines you have running") and immediately enumerates the dimensions returned (world, branch, browser tab/native engine/player, whether another conversation drives it). This is clearly distinguishable from session.connect (which binds) and world.list (which lists worlds).
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?
Gives explicit triggers: call it "when a tool tells you the target is ambiguous" or "before session.connect, to see what there is to choose from." It also names the routing relationship to a sibling, leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the connected world's cover image — captures the current viewport by default.
| Name | Required | Description | Default |
|---|---|---|---|
| as | No | Your own name, when you are one of several agents sharing one connection to this engine (the sub-agents one agent session runs share its connection, so without it the engine sees all of them as one caller). Pass the same name on every call you make. The engine then treats you as a caller of your own: your roster name is this name, and your play session, the play-shadow writes and refusals that say who wrote what, engine.modeOwner, your shell session and your notices are yours alone. Lowercase letters, digits, '-' and '_'. Leave it out when you are the only agent on your connection. | |
| source | No | viewport (default): render and upload the current viewport. vfs_path: upload an image at `vfs_path`. blob_sha256: stamp an already-uploaded blob. | |
| vfs_path | No | Path to an image in the engine VFS (PNG/JPEG/WebP). Used when source=vfs_path. | |
| blob_sha256 | No | Hex sha256 of an already-uploaded image blob. Used when source=blob_sha256. | |
| content_type | No | Override the image MIME type (otherwise inferred from the path extension). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the agent knows this is a destructive, non-repeatable external write. The description adds the useful default-source detail ('current viewport by default') but does not say what gets overwritten (the prior cover), or any auth/connection prerequisites.
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 well-formed sentence with the action front-loaded and the default behavior appended after the em-dash. No wasted words, though being a lone fragment it leaves some completeness on the table.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation with no output schema, the annotations and 100%-covered schema carry most of the load, and the description preserves the essential default. It still omits what the operation replaces and any precondition, which a destructive write would ideally disclose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all five parameters (including the detailed 'as' identity field and the source enum) are fully documented in the schema. The description only corroborates the viewport default and adds nothing beyond the schema, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Set the connected world's cover image') and adds the default source behavior, so the agent knows exactly what the tool does. It does not, however, distinguish itself from the nearby sibling 'world.set_media', leaving a possible routing ambiguity unresolved.
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 'captures the current viewport by default' implies the common usage path, and the schema's source enum elaborates the modes. But the description itself gives no explicit when-to-use vs alternatives, no prerequisites (e.g. a world must be connected), and no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a JavaScript script inside the engine, against the engine's own tool catalogue. Use this instead of several separate tool calls whenever you need to filter, loop over, or combine results: the intermediate data stays in the script rather than passing through the conversation.
Two globals, and nothing else:
zero..(...args) call a tool. Every call returns a promise, so await it. zero.libs...(...args) call a tool a library ships (its toolbox is registered as @::) tools.toolboxes() every toolbox: { toolbox, purpose, toolCount } tools.list(toolbox) the tools in one: { name, signature, description } tools.describe(name) one tool in full: args, returns, examples, types tools.search(query, toolbox?) find a tool by what you want to do tools.use(toolbox, tool, ...args) call by computed name
Start with tools.toolboxes() or tools.search(...) if you do not already know the tool you want, then tools.describe(name) for its exact arguments: they are positional and typed. zero. also reaches a library's toolbox when no other toolbox has that name; a name several hold is refused naming each. await works at the top level. return a value to hand it back; keep it small, and reduce inside the script rather than returning everything you fetched. console.log is captured and returned in logs. The language is ZeroJS: modern JavaScript and its standard library, with no Node or browser APIs.
Sequencing is yours to choose: await a; await b; runs them one after another, while await Promise.all([a, b]) runs them at the same time, which genuinely overlaps, so prefer it for independent calls.
The answer is { ok, value, error, failure, trace, logs }. value is what the script returned. When ok is false, error says what failed and where, and failure.kind is tool (a tool call's rejection ended the script; failure.step and failure.tool name the call), script (the script threw), syntax (it did not parse; the position counts the script's own lines), timeout (it outlived timeoutMs; a value it had returned stays in value), budget (it made more than 200 tool calls) or setup (the script environment could not be prepared). trace lists every call with its step, outcome and duration.
Example:
const hits = await tools.search("read a file"); const [info, text] = await Promise.all([zero.wld.info(), zero.files.read("/source/notes.md")]); return { mode: info.mode, lines: text.split("\n").length, firstHit: hits[0].name };
| Name | Required | Description | Default |
|---|---|---|---|
| as | No | Your own name, when you are one of several agents sharing one connection to this engine (the sub-agents one agent session runs share its connection, so without it the engine sees all of them as one caller). Pass the same name on every call you make. The engine then treats you as a caller of your own: your roster name is this name, and your play session, the play-shadow writes and refusals that say who wrote what, engine.modeOwner, your shell session and your notices are yours alone. Lowercase letters, digits, '-' and '_'. Leave it out when you are the only agent on your connection. | |
| script | Yes | The JavaScript to run. `await` works at the top level; `return` hands back the result. | |
| timeoutMs | No | Wall-clock budget for the whole script, including its tool calls. Default 30000. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare this is not read-only, is open-world, and is destructive, so the safety profile is already stated. The description adds substantial context beyond them: the 200-tool-call budget, timeout semantics, the failure.kind taxonomy, trace/log capture, and sequencing guidance for parallel calls. It does not warn that the script itself can make state-changing calls, which is the one behavioral note a mutation-capable tool of this kind should make explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose statement is front-loaded, and the API reference block and error taxonomy earn most of their space for a meta-tool with a custom DSL. Some material is redundant with the schema (the top-level `await` note repeats the script parameter description), and the note about name collisions with library toolboxes is niche.
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?
There is no output schema, but the description fully specifies the return envelope ({ok, value, error, failure, trace, logs}) and the meaning of each failure kind. For a complex, DSL-carrying tool this is complete enough to call correctly on the first attempt.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the `as` parameter is already documented in depth, so the baseline is 3. The description still adds real value — it warns that tool arguments are positional and typed and directs the agent to tools.describe for exact arguments, plus the 'keep the return small / reduce inside the script' guidance for the script parameter.
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?
Opens with a specific verb and resource: 'Run a JavaScript script inside the engine, against the engine's own tool catalogue.' It also distinguishes the tool from the obvious alternative of making many individual tool calls. However, it never contrasts itself with the sibling execution tools (bash, execute), which an agent must choose between for the same basic job.
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?
Explicit when-to-use: 'Use this instead of several separate tool calls whenever you need to filter, loop over, or combine results.' It also gives an in-script discovery path (tools.toolboxes / tools.search / tools.describe). There is no explicit when-not-to-use case (e.g. a single simple call), though that is strongly implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resume a background task from a promoted execute/bash and return its result when ready. Pass its taskId, or the kickoffId of a call the engine accepted and had not reached yet.
| Name | Required | Description | Default |
|---|---|---|---|
| as | No | Your own name, when you are one of several agents sharing one connection to this engine (the sub-agents one agent session runs share its connection, so without it the engine sees all of them as one caller). Pass the same name on every call you make. The engine then treats you as a caller of your own: your roster name is this name, and your play session, the play-shadow writes and refusals that say who wrote what, engine.modeOwner, your shell session and your notices are yours alone. Lowercase letters, digits, '-' and '_'. Leave it out when you are the only agent on your connection. | |
| logs | No | ||
| taskId | No | Task id from a {status:"running"} response. | |
| logScope | No | Whose work the engine-window log lines in the response may be about (default: caller). One engine serves several agents at once and runs all of their content, so its log holds all of their failures. `logs` says how severe a line must be to appear; this says whose work it may be about, which no severity floor can express, because a neighbour's per-frame error IS an error. `caller` keeps the lines this call's own work raised plus the engine's own, and closes the list with one <n error lines from another caller's work left out> marker when there were any. `all` keeps every caller's, which is what a reader debugging the whole engine wants. The engine's own subsystem lines carry no caller and are kept either way. | |
| kickoffId | No | The kick-off handle to wait on — the `kickoffId` field from a response the engine accepted and had not reached yet (`{ status: "running", kickoffId }`). Resolves to the task the call spawns, then waits on it exactly as `taskId` does. | |
| timeout_secs | No | Inline budget (default/capped 20s). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, covering the safety profile. The description usefully adds that the call blocks/resumes and 'returns its result when ready', but says nothing about timeout behavior (what happens if the 20s budget elapses) or the shape of a not-ready response. Adds some value over annotations, not rich context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action and the handles to pass, with no wasted words. 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?
With annotations present, 6 params (all optional) and no output schema, the description covers the core purpose and the two primary handles. The main omission an agent would want is timeout/cap behavior, but the schema documents `timeout_secs` and the other auxiliary params, so coverage is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is already 83%, so the baseline is 3. The description goes slightly beyond by routing the caller: use `taskId` for a running task, `kickoffId` for an accepted-but-unreached call, tying each handle to its originating response type. Minor added meaning over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb+resource: it resumes a background task spawned by `execute`/`bash` and returns its result. That names the sibling tools that produce the task, so an agent can place it relative to `execute`/`bash` and `pause`. It stops short of fully disambiguating from `pause`, keeping it at a strong 4.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context for use: call it with the `taskId` of a running task, or the `kickoffId` of a call the engine accepted but had not yet reached. It does not explicitly state when NOT to use it (e.g., versus `pause` or polling), so it is clear context without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
How a world is actually doing: plays, players, playtime, the funnel from page view to a session that lasted, retention, and what boots are failing on. The same numbers the creator's dashboard shows, so an answer here and an answer there agree. Reads the world this conversation has open, or the one you name with world. Needs maintainer access: a world you have no role on answers not found. view picks the arrangement (series | breakdown | funnel | retention | performance). Ranges are whole UTC days, up to 400 of them, and a range over 120 days comes back bucketed by week. Counts and durations only: there is no per-player row here and never a name, a place or a session. Read clickhouse_configured before you report a zero, because a deployment that records nothing answers zeros.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Inclusive UTC end day, YYYY-MM-DD. Defaults to today. | |
| from | No | Inclusive UTC start day, YYYY-MM-DD. Defaults to 27 days before `to`, which makes the default window four weeks. | |
| guid | No | The same argument as `world`, under another name: give one of the two. A call giving them two different worlds is refused. | |
| view | No | Which arrangement of the numbers. Defaults to `series`. `series`: Each metric asked for, day by day over the range, with the range's total and the previous range's total beside it. `breakdown`: One metric split by the dimension it carries (a boot failure's class, a connection class), biggest first, each row with its share of the whole. `funnel`: The steps from opening the world's page to a session that lasted a minute, each step with its share of the step before it. `retention`: How many first-time players came back within a day, a week and a month, with the weekly cohort grid behind those rates. `performance`: Time to first frame, how far boots got through the engine's boot timeline, what the failures were and on what connection. | |
| grain | No | Bucket size, `day` (default) or `week`. A range over 120 days is served by week whichever you ask for. | |
| world | No | World guid. Defaults to the world this conversation has open, so a call after world.open or world.connect needs no argument at all. | |
| metric | No | The ONE metric to split. Required by the `breakdown` view and ignored by the others. The metrics with a breakdown: boot_failed, device, platform, browser, renderer, source, referrer, phase_reached, boot_failed_stage, boot_failed_reason, connection_class. | |
| metrics | No | Which metrics the `series` view answers, as a list or a comma-separated string, at most 32. Left off, you get the eight a dashboard leads with. A name outside the list is refused naming the list, never dropped. The metrics, by group: [overview] plays = Play sessions the engine actually opened on this world that day, not Launch button presses. players = People with an account who played at least once that day, counted once per day however many sessions they opened. anonymous_plays = Play sessions with no account behind them, so no person can be counted for them. agent_plays = Play sessions opened by an agent account rather than a person, kept apart so human numbers stay human numbers. playtime_ms = Time spent in play sessions, as the server measured it from heartbeats and rounded down per session, so it is a floor and never an estimate. avg_session_ms = Playtime divided by plays over the range asked for. long_sessions = Play sessions that lasted at least a minute. abandoned_sessions = Play sessions the reaper closed because the tab died or the network went, rather than the player leaving. [funnel] page_views = Opens of this world's page. card_impressions = Times a card for this world scrolled into somebody's view, counted once per card per page they looked at. card_clicks = Clicks on a card for this world anywhere on the site. launches = Launch presses. An intent to play, which is not yet a play. boot_started = Engine boots that began on this world. boot_rendered = Engine boots that drew their first frame. boot_failed = Engine boots that failed, broken down by the failure class the browser reported. [audience] device = Play sessions by the kind of machine they ran on, across the sessions whose browser said: desktop, mobile, tablet or other. platform = Play sessions by operating system, across the sessions whose browser said: Windows, macOS, Linux, Android, iOS or other. browser = Play sessions by browser, across the sessions that said: Chrome, Firefox, Safari, Edge or other. renderer = Play sessions by what the browser could draw with: a WebGPU adapter, WebGL2 only, or nothing. A world needs WebGPU. [acquisition] source = Play sessions by where the play was reached from, across the sessions that could say: a page on this site, another site, an embed, a shared link or an agent. referrer = Play sessions followed in from another site, by which family of site it was. Never a URL and never a search query. [performance] boot_ms_p50 = Median time from the page committing to a boot to its first frame, merged across the days asked for. boot_ms_p90 = The time to first frame nine boots in ten beat, merged across the days asked for. phase_reached = Boots that reached each stage of the engine's boot timeline; the drop-off is the difference between two stages. boot_failed_stage = Failed boots by the last step of the page's boot they reached: boot_start, boot_bundle, boot_worker, boot_canvas or boot_render. A boot that dies before the engine starts reaches no stage of phase_reached, and this is where it stopped. boot_failed_reason = Failed boots by what failed, finer than the class: the GPU, the network, memory, the engine starting or stopping, and the rest of a closed list. Boots from before reasons were recorded have none. connection_class = Boots by the connection class the browser reported: slow-2g, 2g, 3g or 4g. hidden_share_reports = Visits that reported how much of themselves ran with the tab hidden. The denominator of hidden_share_bp. hidden_share_bp_sum = Those visits' hidden shares added together, in basis points. The numerator of hidden_share_bp, and meaningless on its own. hidden_share_bp = The average share of a visit spent with the tab hidden, across the visits that reported one. [community] votes_up = Upvotes cast on this world. votes_down = Downvotes cast on this world. votes_cleared = Votes on this world that were taken back. ratings_liked = People who said they enjoyed this world. ratings_indifferent = People who said this world left them indifferent. ratings_disliked = People who said they did not enjoy this world. comments = Comments left on this world, threads and replies together. bookmarks_on = Times this world was bookmarked. bookmarks_off = Times a bookmark on this world was removed. follows_on = Times somebody started following this world. follows_off = Times somebody stopped following this world. reports = Reports filed against this world. A count only: the reason is never shown here. forks = Times this world was forked into a new one. [building] publishes = Commits finalized on this world. edit_sessions = Editor sessions opened on this world. edit_time_ms = Time spent in the editor on this world, measured the same way playtime is. chat_turns = Agent turns run against this world. chat_credits = Credits those agent turns spent, as a positive number. prs_opened = Pull requests opened against this world. prs_merged = Pull requests merged into this world. [reach] egress_bytes = Bytes of this world's content served out of the blob store. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnly/openWorld/non-destructive, but the description adds substantial behavior beyond that: the 400-day cap, weekly bucketing past 120 days, the no-per-player/no-name/no-place guarantee, auth failure mode returning not-found, and the zero-vs-unconfigured caveat. This is exactly the extra context annotations cannot carry.
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 purpose, then layers scope, auth, view, ranges, exclusions, and the zero caveat in dense but non-redundant sentences. It is long, but the bulk of the metric enumeration lives in the schema rather than the description, so little is wasted here.
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 output schema and 8 parameters, the description carries the load well: it describes what is returned (counts and durations, funnel/retention/performance arrangements), the aggregation constraints, access requirements, and the caveat that a zero may mean unconfigured rather than inactive. Nothing an agent needs to call it correctly 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 100% and the schema itself is extraordinarily rich, documenting every parameter, enum, and metric semantics. The description's parameter content (view arrangement, default four-week window, breakdown-only metric) largely restates the schema, so it adds only marginal meaning beyond it.
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?
Opens with a specific verb+resource framing ("How a world is actually doing: plays, players, playtime, the funnel... retention... what boots are failing on"), and explicitly scopes itself against dashboard parity. An agent can immediately tell this is the read-only analytics surface, not world.list/open/manage siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clear about when the tool works: reads the conversation's open world or one named with `world`, requires maintainer access (no role -> not found), and warns to check `clickhouse_configured` before reporting a zero. It gives prerequisites and context but names no explicit alternative sibling or when-not-to-use condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pin the engine of the world editor the user has open, so engine tools (execute, capture, …) drive it for the rest of this conversation. An engine that is already connected returns at once. It is held only for an engine that is about to connect: once the editor has drawn its first frame the call holds, up to about 30 s, until the engine connects. In every other case it answers at once with connected: false and what the editor is doing (editor.state: never_opened, launching, booting, connecting, stalled, failed, started_not_connected), so while an editor is still loading do what needs no engine and call this again when you need one. waited_ms is how long the call was held (0 when it was not) and wait says how the wait ended. It opens nothing: nothing on the server can open a browser. Call world.open first and act on its next, which says whether you show the user a link or run a command on their machine. A world with engines on more than one branch is refused rather than guessed at: name the branch, or use session.list / session.connect to pick one engine outright.
| Name | Required | Description | Default |
|---|---|---|---|
| guid | No | The same argument as `world`, under another name: give one of the two. A call giving them two different worlds is refused. | |
| world | No | Optional: the guid of the world whose editor you mean (world.list names each of your worlds beside its guid). Omitted, any open editor. A value that is not a guid, a world's name included, is refused and connects nothing. | |
| branch | No | Which branch's engine you mean, when the world has engines on more than one. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds rich behavior beyond the annotations: the blocking semantics (up to ~30 s, held once the editor draws its first frame), the non-blocking path returning connected: false with editor.state, waited_ms and wait, and the multi-branch refusal. Annotations cover safety hints only; the description carries the temporal and failure 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?
Purpose and the blocking rule are front-loaded, and most sentences carry distinct procedural information. It is dense and runs long with several clauses (e.g. the server-cannot-open-a-browser tangent) that could be tightened without loss.
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?
No output schema exists, so the description must explain returns — and it does, enumerating connected, editor.state (with all values), waited_ms and wait. Combined with the routing to world.open, it is complete for calling this tool 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 coverage is 100%, so the baseline is 3, but the description clarifies relationships the schema states separately: guid and world are aliases and a mismatch is refused, omission means 'any open editor', and branch is only required when engines span branches. That adds real selection semantics over the field descriptions.
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 opening sentence states a specific verb and resource: pin the engine of the open world editor so engine tools (execute, capture) drive it for the conversation. It distinguishes itself from siblings world.open (which opens) and session.connect/session.list (which pick an engine outright), so an agent can route correctly without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly covers when to use ('call this again when you need one') and when not ('while an editor is still loading do what needs no engine'), and names alternatives: call world.open first and act on its next; use session.list / session.connect for multi-branch worlds. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new world you own and return its guid + url. Use this to start a fresh build. By default the new world is a DRAFT meant to be public: only its owner (and members) can open it until you call world.undraft, and then it becomes public. Pushing commits does not make a draft public; world.undraft does. Build for a user who wants to share the result as a draft, and undraft it when they say it is ready. Pass visibility (or public) without draft to create a world that is public, unlisted or private from the start.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | World name (a scratch name is generated if omitted). | |
| draft | No | Create the world as a draft (the default when visibility and public are both omitted). false with no visibility creates a private world. | |
| public | No | Older form of visibility: true = public, false = private. visibility wins when both are given. | |
| visibility | No | Who can open the world. Without draft: the world is this from the start (private stays private until someone changes it). With draft: true: what the draft becomes when undrafted (public or unlisted). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only mark this as a non-idempotent write (readOnlyHint=false, openWorldHint=true); the description goes well beyond them, disclosing that the default result is a DRAFT open only to owner+members, that commits do not publish it, that world.undraft is what makes it public, and how visibility interacts with draft. This is exactly the behavioral context an agent needs to avoid a wrong default.
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 action and return values in the first sentence, then layers the draft workflow. Four sentences all earn their place, though the draft/public explanation is slightly repetitive across sentences and could be trimmed marginally.
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 4 optional params, no output schema, and a non-idempotent write annotation, the description supplies everything missing: default behavior, visibility semantics, unpublishing/undraft path, and the return shape (guid + url). Nothing needed to call it correctly is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already well documented (baseline 3). The description earns extra credit by explaining the semantic consequence of the draft/visibility combination ('what the draft becomes when undrafted') and the precedence rules in workflow terms, though it largely restates schema behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Create a new world you own') and even discloses the return payload ('guid + url'). It is clearly distinguishable from sibling operations like world.fork, world.duplicate/restore, or world.list 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?
Explicitly says when to use it ('Use this to start a fresh build') and writes out the decision procedure for draft vs public, naming the complementary sibling world.undraft and the exact moment to invoke it ('when they say it is ready'). It also states the alternative path (pass visibility/public without draft for a public/unlisted/private world).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Soft-delete (move to trash) a world the linked user owns. REVERSIBLE: the world is hidden from every surface but stays recoverable via world.restore for the server's retention window (default 30 days), after which it is permanently purged along with its commits + assets. Pass name (resolved against your own worlds) or guid. Owner-only — fails if you don't own the world. Prefer asking the user before deleting a world you didn't just create.
| Name | Required | Description | Default |
|---|---|---|---|
| guid | No | Already-resolved world guid (skip lookup) | |
| name | No | World name (looked up via world.list) | |
| world | No | The same argument as `guid`, under another name: give one of the two. A call giving them two different worlds is refused. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true and non-idempotent, but the description adds substantial context beyond them: it is reversible, hidden from every surface, recoverable via world.restore for a retention window (default 30 days), then permanently purged along with commits and assets, and it requires ownership. This is exactly the behavioral richness an agent needs for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the action and its reversibility, then moves through parameters, ownership, and the caution. Every sentence carries distinct, necessary information (verb, reversibility, retention, inputs, auth, etiquette) with no wasted prose.
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?
No output schema exists, but the description covers everything an agent needs: reversibility, retention window, what gets destroyed, ownership requirement, input resolution, and the recovery path. Combined with annotations that carry the safety profile, nothing material 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 coverage is 100%, so the guid/name/world aliasing and lookup behavior are already documented in the schema. The description adds a little (name 'resolved against your own worlds'), but this largely repeats what the schema already conveys, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: 'Soft-delete (move to trash) a world the linked user owns.' An agent immediately understands the operation and its scope (owner's world). However, it does not distinguish this from the sibling tool `world.trash`, which reads as a near-synonym, so the agent cannot tell the two apart from the text 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?
Gives clear context: delete a world you own, pass `name` or `guid`, owner-only, and explicitly names the recovery alternative (world.restore) plus a pre-condition preference ('Prefer asking the user before deleting a world you didn't just create'). It stops short of explaining when to choose this over `world.trash`, which is the most obvious ambiguity for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Detach from the current world session.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, so the safety profile is covered structurally. The description adds only that the target is the 'current' session; it says nothing about whether the world state persists, whether it errors when no session is active, or what the non-idempotent behavior implies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence with no filler, and the action and scope are front-loaded. Nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter, no-output-schema tool whose annotations carry the safety profile, the description is minimally sufficient. It nonetheless omits the state prerequisites and post-conditions an agent would want before tearing down a session.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies.
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 (detach) and resource (the current world session), which is enough to distinguish it from world.connect and world.open. It stops short of explicitly naming the inverse sibling, but the action is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to invoke it versus alternatives such as world.connect, session.connect, or session.list, and no prerequisites or state requirements. The word 'current' implies it only applies to an active session, but that is inference rather than stated guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fork an existing world into your namespace — copy someone else's world as a starting point (GitHub-style). Pass source = the world_guid from zeromind.search { scope: 'worlds' } (a foreign world), or a name of one of your own worlds. The fork inherits the source's visibility (a fork of a public world is public — you can't privatise it), and a fork of a draft is a draft meant for the same visibility. Optional name overrides the default "-fork". Returns the new world_guid; open it with world.open { world: <world_guid> } and act on its next, then world.connect { world: <world_guid> } waits for the editor.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Optional new name/title for the fork. | |
| source | Yes | The world_guid to fork (from zeromind.search scope=worlds), or a name of your own world. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare the generic write profile (readOnly=false, destructive=false, idempotent=false, openWorld=true). The description goes well beyond them by disclosing visibility inheritance (a fork of a public world stays public; you cannot privatise it), draft-inherits-draft semantics, the default name pattern, and the returned world_guid. These are non-obvious behaviors an agent could not infer from structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the core action, and every sentence carries distinct information (source sourcing, visibility/draft rules, return value and next steps). Slightly dense due to the embedded follow-up chaining, but nothing is redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description states what is returned (the new world_guid) and how to consume it (world.open, then poll via world.connect). Combined with the visibility, naming, and draft-inheritance details, an agent has everything needed to call and chain this tool 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 coverage is 100%, so the baseline is 3. The description adds real meaning: `source` may be either a foreign world_guid (with its retrieval route) or the name of one of the caller's own worlds, and `name` overrides the default "<name>-fork" naming convention.
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 (fork) and resource (world) plus the semantics of the operation — 'copy someone else's world as a starting point (GitHub-style)'. This clearly distinguishes it from siblings like world.create or world.list, and the agent knows exactly what outcome to expect.
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?
Tells the agent where the `source` value comes from (zeromind.search { scope: 'worlds' } for a foreign world, or a name of your own world) and gives the follow-up sequence world.open then world.connect. It lacks an explicit when-not or a named alternative such as world.create, but the usage context is otherwise unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record a launch of the world and answer where it opens: the browser URL and the zero:// URL an installed desktop engine answers to, both the EDITOR — the engine that comes up is one this conversation can work in and what is done in it persists — plus the launch counters. Nothing opens from the server — the opening happens on the user's machine, and next says who does it (a harness with a shell runs zeromind open <guid>; anyone else shows the user the link). The engine that comes up binds to this conversation on its own, so engine tools work with no connect call; world.connect waits for it explicitly. Pass name (preferred) or guid.
| Name | Required | Description | Default |
|---|---|---|---|
| guid | No | Already-resolved world guid (skip lookup) | |
| name | No | World name (looked up via world.list) | |
| world | No | The same argument as `guid`, under another name: give one of the two. A call giving them two different worlds is refused. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnly=false, idempotent=false, destructive=false), it discloses substantial behavior: nothing opens server-side, the opening occurs on the user's machine, `next` indicates who performs it, and the engine binds to this conversation automatically. It also reveals the side effect of incrementing launch counters, none of which the annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The opening clause is well front-loaded, but the middle devolves into a tangled em-dash aside ("both the EDITOR — the engine that comes up is one this conversation can work in and what is done in it persists — plus the launch counters") that is hard to parse. The content is relevant, but the packaging is denser than it needs to be.
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 output schema, the description usefully compensates by explaining the return values (browser URL, zero:// URL, counters) and the meaning of `next`. The main omissions are error/failure behavior and permissions, but for a launch tool it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 100%, so the baseline is 3, but the description adds a preference the schema does not state: "Pass `name` (preferred) or `guid`." This gives the agent an ordering hint for otherwise fully documented parameters, though it adds nothing about the `world` alias already covered by the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
It states a specific verb+resource ("Record a launch of the world and answer where it opens") and names what it returns (browser URL, zero:// URL, launch counters), which sets it apart from an ordinary open. It only partially differentiates from close siblings like world.open and world.open_in_browser, which are never mentioned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It contrasts with world.connect ("world.connect waits for it explicitly") and explains that the engine self-binds, which is real routing guidance. However, it never tells the agent when to pick world.launch over world.open or world.open_in_browser, and no prerequisites or when-not conditions are given for the launch action itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the worlds you own. Each entry names the world's branches and which of them is its default, so you can see a world holds work on more than one branch before opening it.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description goes further by disclosing the shape of each result entry (branches plus which is default), which is real added value given there is no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, purpose front-loaded, and the second sentence earns its place by explaining what an entry contains and why that matters. No filler or repetition of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only list tool with annotations covering safety, the description supplies the one thing structured fields do not: what each entry returns and the branch/default distinction. Return pagination or result-size behavior is unaddressed, but that gap is minor here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the schema description burden is nil and the baseline of 4 applies. The description correctly says nothing about inputs and instead spends its words on result content.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource with a scope qualifier ("the worlds you own"), which clearly separates it from world.create/delete/open. It never names a sibling tool explicitly, so an agent must infer the boundary itself rather than being told.
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?
"before opening it" implies a pre-inspection use case, so the moment to call it is suggested rather than stated. No exclusions and no comparison to adjacent readers like world.analytics or session.list, leaving routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open a world in the editor. With an engine to open it in — one this conversation is already driving, or one you name with session from session.list — this MOVES that engine to the world and answers {switched, session_id, world, branch}; engine tools then act on it with nothing else to call. Otherwise it records that you want the world open and answers where it opens: the browser URL and the zero:// URL an installed desktop engine answers to. Nothing opens from the server — the opening happens on the user's machine, and next says who does it (a harness with a shell runs zeromind open <guid>; anyone else shows the user the link). The engine that comes up binds to this conversation on its own, so engine tools work with no connect call; world.connect waits for it explicitly. An engine you did not name is never taken: when you have engines running, the answer lists them under engines so you can ask the user which to reuse, and any engine another conversation is driving (claimed_by_another) is refused — the one you are driving included, if somebody else has taken it since. Requires edit access (use world.create for a new world). A world you have deleted is refused here — world.trash lists it and world.restore brings it back. The editor binds the world's live working copy: naming a branch checks the name against the world's branches but does not yet choose what the editor loads — branch selection is coming. The result lists the world's branches.
| Name | Required | Description | Default |
|---|---|---|---|
| guid | No | The same argument as `world`, under another name: give one of the two. A call giving them two different worlds is refused. | |
| world | Yes | World guid to open in the editor (world.list names each of your worlds beside its guid). A name is not a guid and is refused. | |
| branch | No | Which branch you mean (world.list names each world's branches). The name is checked — one the world does not have is refused, listing the ones it has — and reflected back as `open.branch`. It does not yet choose what the editor loads: the editor binds the world's live working copy either way. | |
| session | No | Open the world in THIS engine, by its session id from session.list. It must be one of yours and not one another conversation is driving. With no `session`, the engine this conversation already drives is the one moved, and a conversation driving none is answered with the addresses instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds substantial non-obvious behavior: nothing opens server-side, `next` identifies who performs the action, engines claimed by another conversation are refused, edit access is required, and branch naming is validated but not yet used for loading. This is rich context beyond what annotations provide.
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-loaded with the primary action and no throwaway sentences, but the density of parenthetical asides and em-dash clauses makes it heavier than necessary. Every sentence carries information, but the prose could be tightened without losing meaning.
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?
There is no output schema, so the description must describe returns — and it does: {switched, session_id, world, branch}, the browser and zero:// URLs, `next`, and the `engines`/`claimed_by_another` listing. Nothing an agent needs to call this correctly or interpret the result 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 coverage is 100%, so the baseline is 3; however the description adds cross-parameter interaction semantics — with `session` the named/driven engine is moved, without it the addresses are returned, and `guid`/`world` are aliases that must agree. That goes beyond the per-field schema text.
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?
First sentence gives a specific verb+resource ('Open a world in the editor') and immediately distinguishes the two modes: MOVES an existing engine vs records intent and returns addresses. It differentiates from siblings world.connect, world.open_in_browser, and world.create by name, so an agent can route without opening another 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?
Explicitly states when to run with an engine vs without, names the alternative for waiting ('world.connect waits for it explicitly'), points to world.create for new worlds, and to world.trash/world.restore for deleted ones. The condition selecting each path is spelled out rather than inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Answer where a world opens, addressed by name: the browser URL and the zero:// URL an installed desktop engine answers to, plus next, the one sentence naming who opens them. The server opens neither. Like world.open it records that you asked for this world, so the engine that comes up binds to this conversation on its own. Use world.open when you are going to edit the world — it also checks edit access and the branch you name. Pass name (looked up via world.list) or guid (already-resolved).
| Name | Required | Description | Default |
|---|---|---|---|
| guid | No | Already-resolved world guid (skip lookup) | |
| name | No | World name (looked up via world.list) | |
| world | No | The same argument as `guid`, under another name: give one of the two. A call giving them two different worlds is refused. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations present the bar is lower, and the description still adds real value: 'The server opens neither' and 'it records that you asked for this world' explain why readOnlyHint=false and idempotentHint=false despite the tool appearing to just resolve URLs. This reconciles the non-read-only, non-idempotent profile with observable behavior rather than contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core deliverable (the two URLs plus `next`) is front-loaded, and the exclusion of world.open follows. Some clauses are dense and a touch circuitous, but there is little outright waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description compensates by naming the returned pieces (browser URL, zero:// URL, next sentence). Combined with the annotations covering the open-world side effect, an agent has enough to call it correctly; only the exact response shape remains unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents guid, name, and the world alias. The description's 'Pass `name` (looked up via world.list) or `guid` (already-resolved)' largely restates the schema's own text. Baseline 3 is appropriate since the structured field does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific resource and outcome - it returns the browser URL and `zero://` URL where a world opens, plus a `next` field naming the opener. It explicitly distinguishes itself from world.open, so an agent can tell what it does apart from siblings. The framing 'Answer where a world opens' is slightly indirect but the substance is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit routing rule: use world.open when you intend to edit, because that tool also checks edit access and the branch. This names the alternative and the selecting condition. It stops short of stating the affirmative 'use this when you only need to know where it opens,' leaving one small inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recover a soft-deleted world before it's permanently purged. Pass name (resolved against the trash list — a trashed world is NOT in world.list) or guid (e.g. from world.trash). Owner-only. 404s if the world was already purged.
| Name | Required | Description | Default |
|---|---|---|---|
| guid | No | Already-resolved world guid (skip lookup) | |
| name | No | Trashed world name (looked up via world.trash) | |
| world | No | The same argument as `guid`, under another name: give one of the two. A call giving them two different worlds is refused. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnly false, destructive false, openWorld true, non-idempotent false), and the description adds real context on top: owner-only authorization, trash-list resolution semantics, and a 404 if the world was already purged. It omits what happens on a repeat call or when multiple trashed worlds share a name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, no filler, with the core recovery action and its time-limited nature front-loaded before the identifier guidance.
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 no output schema, the description covers the essentials an agent needs: identifier options, permission requirement, and failure mode. Non-idempotent retry behavior and name-collision handling remain unexplained but are minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3; the schema already documents `guid`, `name` lookup, and the `world` alias with its conflict-refusal rule. The description adds some resolution nuance but never mentions the third `world` parameter, so it does not exceed the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Recover a soft-deleted world') plus the scope boundary ('before it's permanently purged'). It is clearly separable from siblings like world.trash, world.undraft, and world.list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes the agent to the right identifier source: `name` resolved against the trash list, or `guid` 'e.g. from world.trash', and warns that a trashed world is NOT in world.list. It also states the owner-only precondition and the 404 outcome, though it never names a competing alternative tool (e.g. world.undraft) to disambiguate against.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the world's media gallery — the screenshots and video trailer shown on its page, in order. Each entry names its bytes with capture (render the connected world now), vfs_path (an image in the world VFS), or sha256 (a blob already uploaded via POST /v1/content/{sha}, the only way to attach a video). Replaces the uploaded gallery, so pass append:true to keep what is already there.
| Name | Required | Description | Default |
|---|---|---|---|
| guid | No | The same argument as `world`, under another name: give one of the two. A call giving them two different worlds is refused. | |
| world | No | World guid (defaults to the connected world). | |
| append | No | Keep the world's current uploaded entries and add these after them (default false = replace). | |
| entries | Yes | The ordered gallery, max 20 entries. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, readOnlyHint=false, and idempotentHint=false, and the description reinforces the destructive replace semantics with the append:true escape hatch. It also discloses that sha256 is the only way to attach a video, a non-obvious constraint. Missing detail on auth or rate limits, so not a full 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences: purpose first, entry mechanism second, replace/append caveat last. Every sentence carries load and nothing is padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, non-idempotent mutation with no output schema, the description covers what gets replaced, how entries are ordered and sourced, and the append escape hatch. The max-20 limit lives in the schema, so nothing critical is missing, but it does not discuss failure modes or result reporting.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: it explains the three byte-naming strategies (capture/vfs_path/sha256), that capture takes the capture tool's arguments, and that video entries require sha256. This goes beyond restating the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb (Set) and resource (the world's media gallery / screenshots and video trailer shown on its page), and specifies the ordering and entry model. It is clearly distinguishable from siblings like set_world_cover or edit_world_metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains the key behavioral choice an agent faces — that the call replaces the uploaded gallery, so append:true is needed to keep existing entries — which is real when-to-use guidance. It does not explicitly route to or away from named sibling tools, keeping it 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.
List the linked user's soft-deleted (trashed) worlds and how many days each has left before it's permanently purged. The recovery surface for world.restore.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish the safety profile (readOnly=true, destructive=false, openWorld=true). The description adds behavior beyond that: it discloses that results include a purge countdown and are scoped to the linked user. It stops short of describing pagination or exact return shape, so not a 5.
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 tight sentences with no filler. The core purpose (list trashed worlds + retention) is front-loaded, and the sibling relationship is a useful second sentence.
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 parameters and no output schema, the description carries the return-value burden itself, and it does: it names what is returned (trashed worlds plus days remaining before purge). Nothing an agent needs to invoke this correctly 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?
The tool takes zero parameters, so there is nothing for the description to disambiguate. The baseline for a 0-param tool applies; the schema is trivially empty and needs no elaboration.
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), resource (soft-deleted/trashed worlds), and scope (linked user's), plus the value it surfaces (days left before purge). It is clearly distinguishable from world.list (live worlds) and directly ties to the recovery flow, so an agent can tell it apart from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Labels itself 'the recovery surface for world.restore,' which tells the agent when it is relevant and which sibling follows it. There are no explicit exclusions or negative conditions, but the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Take a draft world out of draft: it becomes the visibility it was created for (public unless it was drafted as unlisted), or the visibility you pass. This is the one step that makes a draft world openable by other people. It is not refused when the world has nothing to play yet: the answer's playable says whether visitors get a game or an empty page. Undrafting a world that is not a draft changes nothing and says so (undrafted: false). Needs edit access. Acts on world (guid) or on this conversation's world.
| Name | Required | Description | Default |
|---|---|---|---|
| guid | No | The same argument as `world`, under another name: give one of the two. A call giving them two different worlds is refused. | |
| world | No | World guid. Omit to act on this conversation's world. | |
| visibility | No | Undraft to this instead of what the draft was meant for. private turns the draft into a plain private world. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile, and the description adds value beyond them: it discloses the edit-access requirement, the fact that it is not refused on an empty world, and the `playable`/`undrafted: false` outcome semantics. It stops short of describing side effects on existing visitors or sessions.
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 action and outcome, then layers edge cases. Every sentence carries information, though it is dense and slightly long for a single-operation 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?
With no output schema, the description compensates by explaining return fields (`playable`, `undrafted`), the auth requirement, and the no-op path. An agent has everything needed to call it correctly and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so the baseline is 3, but the description adds real meaning: what `visibility` defaults to when omitted (the draft's intended visibility, public unless drafted unlisted) and what 'private' does to a draft. That is semantics beyond the enum descriptions.
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 ('take a draft world out of draft') and the precise outcome: it becomes the visibility it was created for or the passed `visibility`. The line 'the one step that makes a draft world openable by other people' distinguishes it from sibling visibility/launch tools an agent might otherwise confuse it with.
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?
Gives clear triggering context (undrafting a draft, requires edit access) and clarifies the no-op case for non-drafts. It does not explicitly name or rule out sibling alternatives (e.g., world.launch), so routing is implied rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write a file or folder to the world VFS (creating parents). A file the user attached or uploaded goes in with source (one file) or sources (a folder), from the file link the client supplies, so its bytes transfer directly. content is for text; content_b64 only for a small binary you generated in memory, never for a file that exists somewhere. local_path is not the way to send a file from the user's computer: it is read by a native engine on the engine's machine, inside its own transfer directory. Returns bytes written and any LSP diagnostics.
| Name | Required | Description | Default |
|---|---|---|---|
| as | No | Your own name, when you are one of several agents sharing one connection to this engine (the sub-agents one agent session runs share its connection, so without it the engine sees all of them as one caller). Pass the same name on every call you make. The engine then treats you as a caller of your own: your roster name is this name, and your play session, the play-shadow writes and refusals that say who wrote what, engine.modeOwner, your shell session and your notices are yours alone. Lowercase letters, digits, '-' and '_'. Leave it out when you are the only agent on your connection. | |
| path | Yes | ||
| quiet | No | Suppress automatic import callbacks while populating a folder; then run the importer explicitly. | |
| source | No | File reference to download into path; maximum 8 MiB. Use instead of inline content. | |
| content | No | UTF-8 text (or base64 when encoding=base64). | |
| durable | No | Write canonical world source while play is running. | |
| sources | No | Folder contents as file references with relative_path (or file_name). path names the destination folder. Writes in order; on failure reports completed files and the failed path. | |
| encoding | No | ||
| local_path | No | Read by the connected native Zero engine, on the engine's machine, and only inside its transfer directory: %LOCALAPPDATA%\OrigoZero\Transfers on Windows, ~/Library/Application Support/OrigoZero/Transfers on macOS, $XDG_DATA_HOME/OrigoZero/Transfers (default ~/.local/share/OrigoZero/Transfers) on Linux. Pass an absolute path inside that directory or a path relative to it, such as Blender/model.glb; something running on that machine must already have put the file there. This is not how to send a file from the user's computer or from yours. For a folder, `path` is the destination folder and every file keeps its path relative to the folder. At most 256 MiB and 10000 files per call; symlinks and junctions are rejected. A browser engine refuses local paths. Not combined with content, content_b64, encoding or source. | |
| awaitImport | No | When false, the write answers as soon as its bytes land, without waiting for an import they set off to settle, and the answer carries no `import`. For a run of writes that belong together (a model, then the buffer and textures it references), so no file of the run waits on an earlier one's import; `require("@builtin::assetTypes.importer.shared").writeOutcomes(paths, sinceFrame)` then answers where each one's bytes went. | |
| content_b64 | No | Base64 binary (overrides content), only for a small binary you generated in memory. A file the user attached goes in through `source`, never through here. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructive/openWorld/non-idempotent, and the description still adds substantial behavioral context beyond them: return values ('bytes written and any LSP diagnostics'), parent creation, the 8 MiB source cap, 256 MiB/10000-file local_path cap with symlink rejection, browser-engine refusal, and the import-callback timing controlled by `quiet` and `awaitImport`.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded in the first clause and every sentence carries actionable information, but the description re-states schema-level detail for local_path and content_b64, and some sentences are long and clause-heavy. Mostly efficient, with minor redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter, nested-object mutation tool with no output schema, the description is thorough: it covers the return payload (bytes written + LSP diagnostics), partial-failure behavior for folder writes ('reports completed files and the failed path'), and per-mode size/engine constraints. Nothing an agent needs to call it correctly 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?
With 82% schema coverage the baseline is 3, and the description earns above it by explaining cross-parameter semantics the schema does not: mutual exclusivity ('Not combined with content, content_b64, encoding or source'), content_b64 overriding content, and the source-vs-content-vs-local_path decision. It does duplicate some schema text (local_path, content_b64) rather than adding to it, keeping it short of a 5.
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?
Opens with a specific verb+resource: 'Write a file or folder to the world VFS (creating parents).' It then crisply delineates the tool's four content modes (source/sources, content, content_b64, local_path), so an agent understands exactly what this tool does versus edit_file or bash 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use and when-not-to-use rules: attached/uploaded files go through `source`/`sources`, `content` is for text, `content_b64` is only for a small in-memory binary, and `local_path` 'is not the way to send a file from the user's computer.' Alternatives are named and the selecting condition for each is stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Contribute back to ZeroMind. action: 'vote' (value 1 up / -1 down / 0 clear; target world|asset|comment), 'comment' (target world|asset, body, optional parent for replies), 'review' (structured agent quality review on an asset — compat_tier compatible|shim|incompatible + usability/code_quality/performance 0–100 + optional verdict; requires the asset_review scope an admin delegates to a reviewer agent, or admin; the asset must be one you can read, and a shim_asset_guid needs you to maintain the asset's world), 'bookmark' (target world|asset, on), 'follow' (target world|user, on), 'report' (target world|asset, reason), 'record_pull' (mark that consumer world_guid adopted asset_guid — raises its adoption signal). Vote on and comment about content you used; review it once you've judged its quality.
| Name | Required | Description | Default |
|---|---|---|---|
| on | No | bookmark/follow toggle (default true). | |
| body | No | comment text. | |
| guid | No | Target guid (world/asset/comment/user id) for most actions. | |
| note | No | report: optional detail. | |
| value | No | vote: 1 (up), -1 (down), 0 (clear). | |
| action | Yes | ||
| parent | No | comment: parent comment id for a threaded reply. | |
| reason | No | report reason. | |
| target | No | ||
| verdict | No | review: short prose verdict (≤600 chars). | |
| usability | No | review 0–100. | |
| asset_guid | No | record_pull: the asset that world adopted. | |
| world_guid | No | record_pull: the consuming world. | |
| compat_tier | No | review. | |
| performance | No | review 0–100. | |
| code_quality | No | review 0–100. | |
| resolved_commit | No | record_pull: pinned commit of the asset's world. | |
| shim_asset_guid | No | review: pointer to a compat shim asset you published. | |
| with_compat_layer | No | record_pull: was a compat shim used. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only give the generic mutation/open-world flags; the description adds non-obvious prerequisites: review requires the asset_review scope delegated by an admin, the asset must be readable, and a shim_asset_guid requires maintaining the asset's world. It also discloses the semantic effect of record_pull ("raises its adoption signal"), which is behavioral context the schema cannot convey.
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-loaded with the tool's purpose, and the per-action parentheticals are information-dense rather than padded. Some clauses restate the schema verbatim (e.g. "value 1 up / -1 down / 0 clear"), which is mild redundancy, but overall every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 19-parameter, action-multiplexed mutation tool with no output schema, the description covers triggers, permissions, target constraints, and action-to-parameter mapping. It does not describe what any action returns or how failures surface, which is the main remaining gap given the absence of an output schema.
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?
With 19 parameters and action-discriminated behavior, the schema alone cannot tell an agent which fields apply to which action. The description supplies exactly that mapping (vote→value/target, comment→target/body/parent, review→compat_tier plus three 0–100 scores and verdict, record_pull→consumer world/asset), which is high-value semantics beyond the 89% schema coverage.
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?
"Contribute back to ZeroMind" names the resource, and the enumerated actions (vote/comment/review/bookmark/follow/report/record_pull) make the scope concrete and distinguishable from siblings like zeromind.install or zeromind.issue. It stops short of explicitly routing the agent away from any named alternative, so it is clear but not sibling-differentiating at the top level.
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 closing sentence gives a genuine decision rule: vote/comment on content you used, review once you have judged quality. Each action also states its permissible target types (vote: world|asset|comment; comment: world|asset; etc.), which is real usage context. No explicit when-not or named alternative tool, 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.
Long-form ZeroMind guides — what it is, how to use it, the library tools, the engine workflow. Call this any time you want depth beyond the MCP instructions you already saw on initialize. No topic lists available topics; pass topic for one of: getting-started, library, workflow, tools.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | No | Which guide to return. Omit to list them. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description's only extra behavioral fact is that omitting `topic` returns a list rather than a guide, which largely restates the schema's own parameter description rather than adding new disclosure.
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 tight sentences, front-loaded with the resource and its scope, followed by the usage trigger and the parameter modes. Minor redundancy in re-listing the four enum values already present in the schema, but no wasted prose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, read-only documentation tool with no output schema, the description communicates what content is returned and the two calling modes, which is enough to invoke it correctly. Only the overlap with the `guides` sibling is left 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 100% and the enum is fully spelled out, so this is the baseline-3 case. The description repeats the four enum values and the omit-to-list behavior instead of adding format, sizing, or selection guidance beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource (long-form ZeroMind guides) and enumerates the subject matter covered: what it is, how to use it, library tools, engine workflow. It is clear what an agent gets back, but it never distinguishes itself from the `guides` sibling, which plausibly serves a similar role.
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?
"Call this any time you want depth beyond the MCP `instructions` you already saw on initialize" gives a concrete trigger condition relative to information the agent already holds. It does not name a when-not case or point at the `guides` sibling as the alternative, so routing is clear but not fully disambiguated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What worlds or assets found via zeromind.search say they are, from their metadata. Pass SEVERAL guids at once: a whole shortlist is one call, not five. It carries no content bytes; an asset's read is the command that starts reading its implementation in the engine's bash (zm ls-tree @<guid>, then zm grep / zm show / zm log), which is how you tell whether it does the job before you install it. AN ASSET answers with guid, name, assetType (plus type_guid when the type is somebody's own, which is the only way to name one), summary — what the thing is, in prose — description and readme, the author's own words and more of them than a search hit carries, tags, schema/provides_schema, about (what its own metadata says it HAS: the components a bundle spawns with, whether its rig is a humanoid one), the world it lives in with that world's title and licence, its owner (with owner_bot when that account is an agent's), counts of what other people did with it, votes, created/updated, and latest — the version an install pins, and the day it was written; issues when something stands open against it; and read, the zm command that starts reading its code. An asset with a preview image also answers with preview_description (what the preview shows, in words) and returns the thumbnail itself as an image block beside this JSON, at most 4 per call: images names the guid each image block belongs to, in order, and images_omitted names the guids left out and why. A WORLD answers with title, summary, description, owner, license, visibility, the branch a read resolves to and the others it has, counts, votes, dates, and published: what it publishes, in the order its own listing ranks it, each with its own summary. A field with nothing in it is absent rather than empty. results matches the guids by position; one that is private, deleted, or of the other scope is reported against that guid and does not fail the rest.
| Name | Required | Description | Default |
|---|---|---|---|
| guid | Yes | One guid, or several separated by commas ('a,b,c'), from search hits. Up to 100 per call. | |
| sort | No | view=published only: hot | top | popular | new. | |
| view | No | How much to return per guid. ASSETS: 'overview' (default) = everything that decides reuse, and 'detail' is the same answer; 'similar' = the assets nearest this one in the index, each projected as a search hit with its `similarity`, for when the hit was close but not right. WORLDS: 'overview' (default) = the world and what it publishes, in one call; 'summary' = the world alone, without its shelf; 'published' (alias 'contents') = just the listing, which is what `assetType`/`sort`/`limit` narrow. | |
| limit | No | How many entries per guid for the list-shaped views (world published, asset similar). Not a cap on how many guids you may pass — that is 100. | |
| scope | No | What these guids ARE: 'assets' (default) or 'worlds'. The same two values zeromind.search takes. | |
| assetType | No | view=published only: narrow a world's listing to one or more asset types. Builtin types by name, anything else by its type guid. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/openWorld/non-destructive annotations, it discloses that no content bytes are returned, that at most 4 preview images come back with the `images`/`images_omitted` accounting, that absent fields are omitted rather than empty, and that a private/deleted/other-scope guid is reported per-guid without failing the rest of the call. That is exactly the kind of failure-mode and payload-shape context annotations cannot carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded in the first sentence, but the body is a very long, densely packed enumeration of every return field with inline commentary. Since no output schema exists this documentation has value, but the wall-of-text presentation makes it hard to scan and several clauses restate schema-level facts.
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 output schema, the description carries the full burden of documenting returns, and it does so exhaustively for both the asset and world result shapes, plus error isolation and image-block behavior. For a 6-parameter, two-scope tool of this complexity, an agent has everything needed to call and interpret it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all six parameters (including the rich `view` mode semantics and the 100-guid cap). The description reinforces some of this (asset `similar`, world `published`, image limit) but adds little syntax or format detail the schema lacks, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific resource and operation: reporting what worlds/assets 'say they are, from their metadata', keyed on guids from zeromind.search. It explicitly distinguishes itself from content reading ('carries no content bytes') and points to `read`/bash for implementation, so siblings are differentiated. The opening construction is indirect and wordy, which keeps it short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives concrete usage guidance: 'Pass SEVERAL guids at once: a whole shortlist is one call, not five', and names the `similar` view for 'when the hit was close but not right'. It also implies the pre-install inspection workflow ('how you tell whether it does the job before you install it'). What is missing is an explicit when-not-to-use statement versus zeromind.search and zeromind.preview.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Install ZeroMind content INTO the connected world — the step that wires found content into the project. Do not hand-write Luau or guids into execute(); pass the id from a search or inspect hit and this runs the right engine call, with the engine fetching every byte from ZeroMind itself. Pass world (a world guid) to add a whole world as a reusable library, or guid (an asset guid) to install an asset. INSTALL SEVERAL AT ONCE: both take a list — ten assets is one call, not ten. results matches the ids by position, and one that fails is reported against its id without failing the rest. Requires a connected world (call world.connect first). Install the candidate whose code you read and compared (zm ls-tree / zm grep / zm show / zm log @<guid> in the engine's bash), then verify it does the job; if it does not, remove what it wrote and install the next candidate.
| Name | Required | Description | Default |
|---|---|---|---|
| as | No | library: the @<name> stem to mount under. One world per call. | |
| at | No | asset: the directory to install into (default /source); applies to every asset in the call. | |
| ref | No | Pin to a branch/tag/commit. One subject per call. | |
| guid | No | Install these assets: one guid, several separated by commas ('a,b,c'), or an array. Up to 50 installs per call. | |
| world | No | Install these worlds as libraries: one guid, several separated by commas ('a,b,c'), or an array. Up to 50 installs per call. | |
| commit | No | library: pin to a concrete commit id. One world per call. | |
| target | No | Usually inferred. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, openWorldHint=true, and idempotentHint=false, so the safety profile is covered. The description adds useful non-obvious behavior: batching up to 50, per-id partial-failure reporting, and the fact that the engine fetches bytes itself. It stops short of stating what existing files an install overwrites or how re-installing behaves.
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 verb and scope, and each sentence carries distinct information (mechanism, alternatives, batching, prerequisites, workflow). It is on the long side and the closing verification paragraph borders on process advice, but nothing is truly wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 optional params and no output schema, the description compensates well: it explains prerequisites, batch limits, and partial-failure reporting. The main remaining gap is the return shape beyond 'results matches the ids by position' and whether repeated installs overwrite prior output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real semantics beyond the schema: the guid-vs-world duality (asset vs reusable library), batching with 'ten assets is one call', and that 'results' matches ids by position. That positional-result mapping is not something the schema conveys.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Install ZeroMind content INTO the connected world') and clarifies the mechanism: it runs the engine call instead of hand-writing Luau into execute(). It also implicitly separates itself from zeromind.search/inspect by positioning itself as the step after found content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states the prerequisite ('Requires a connected world (call world.connect first)'), where the id comes from (a search or inspect hit), and the workflow: install the candidate whose code you read, verify it, and remove/replace it if it fails. This is strong when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
File an issue, feedback, or a report about the ZeroMind PLATFORM itself: an API call that failed in an unexpected/contradictory way, installed library content that's broken or won't load, docs/guides/tool descriptions that misled you, or a capability you needed and couldn't find. Fire-and-forget — returns an id immediately; the ZeroMind team reviews asynchronously and there is no read-back. NOT for bugs in your own world/code, and NOT for flagging someone's content (use zeromind.engage action:'report' for content moderation). Plugin version and harness are attached automatically. Keep the body factual: what you did, what you expected, what happened, repro steps if you have them.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | What happened / what you expected / repro steps. Required, ≤16 KB. | |
| kind | No | Default 'feedback'. 'bug' = something is broken; 'report' = a longer write-up (test/eval results, structured findings). | |
| title | No | One-line summary, ≤200 chars. | |
| asset_guid | No | The asset this is about, from a search or inspect hit; leave out for a world-level report. A report against an asset counts against that asset AND against the world holding it (the world is read from the asset, so you don't pass both). Reports are shown on what they name and weigh on where it ranks — and one account is one voice per thing, so filing again about the same asset adds nothing. | |
| world_guid | No | The world this is about, when the report is about a whole project rather than one piece of it. Ignored when `asset_guid` is given. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations mark it as a non-idempotent mutation, but the description adds substantial context beyond them: it is fire-and-forget, returns an id immediately, has no read-back, is reviewed asynchronously, auto-attaches plugin version and harness, and dedupes ('one account is one voice per thing, so filing again about the same asset adds nothing').
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, then exclusions, then behavior, then body guidance. Every sentence carries information, though the single dense paragraph is a touch long for a tool with rich schema coverage.
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?
Covers purpose, selection criteria, exclusions, async/no-read-back behavior, and auto-attached metadata; with a 100%-covered schema and no output schema, nothing an agent needs to invoke it correctly 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 100%, so the schema already documents body, kind, title, asset_guid, and world_guid thoroughly (including the asset-vs-world interaction). The description reinforces this with the 'keep the body factual' guidance but adds no new parameter-level syntax or format detail, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (file) and resource (an issue/feedback/report about the ZeroMind PLATFORM itself) and enumerates the concrete trigger categories. It also explicitly distinguishes itself from the sibling zeromind.engage, so an agent can route correctly without opening schemas.
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?
Gives explicit when-to-use triggers (failed API call, broken library content, misleading docs, missing capability) AND explicit exclusions ('NOT for bugs in your own world/code', 'NOT for flagging someone's content'), naming the alternative tool with its exact action for the content-moderation case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Preview exactly what zeromind.install WOULD write, without writing anything. Returns the resolved closure tree — every file and dependency with its local dest_path, byte size, content hash, and why it is included (root / requires / depends_on / conforms_to / tree_child) — plus rollup totals, a truncated flag and a withheld flag (true when part of the graph was left out: it lives in a world you cannot read, or its world no longer ships it, and then unshipped lists its guids). What the content references in ANOTHER world is not a node: worlds lists each such world with the commit it is pinned at and every reference site, naming the node that holds it (from) and the asset it resolved to (names). For an entry with a commit, the install brings the named assets in from that world at that commit (nothing when your world already pins that world at that commit). An entry whose commit is null brings nothing: its sites resolve against the world you install into, which must already open that library. A site marked engine_surface brings nothing either: the running engine provides it. Nodes cover what the published reference tables state and nothing more: content whose files reference assets no table recorded (often content published before the engine recorded that kind of reference) previews and installs without them. Use it on the candidate you picked, after reading its code with zm in the engine's bash, to see its footprint before you install it, especially when it pulls in dependencies you did not expect. Needs no connected world.
| Name | Required | Description | Default |
|---|---|---|---|
| at | No | Destination DIRECTORY the install would use (the asset keeps its own name), used to compute each node's dest_path. e.g. at=/source/combat → /source/combat/<name>. Defaults to /source. | |
| ref | No | Preview the asset at a ref, read as zeromind.install reads it: a commit id, a branch or tag of the asset's world, or one of the asset's own version ids. A ref that names none of these is an error. Omitted or empty, the preview shows what the asset's world ships. | |
| guid | Yes | The root asset guid to preview (from a zeromind.search / zeromind.inspect hit). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/safe/openWorld, and the description adds substantial context beyond them: the resolved closure tree fields (dest_path, size, hash, inclusion reason), rollup totals, the truncated and withheld flags, the unshipped guid list, and cross-world `worlds` entries with commit pinning and reference sites. It also discloses a real limitation — nodes cover only what published reference tables state, so unrecorded references are silently absent from the preview.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded correctly in the first sentence, but the body is a wall of dense run-on clauses about cross-world resolution, null commits, engine_surface sites, and reference-table coverage. Every clause is substantive, yet the lack of structure makes the return semantics hard to parse on a first read.
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?
There is no output schema, and the description compensates by fully explaining the shape of the returned tree, rollups, flags and cross-world entries, plus the install semantics of each kind of entry. For a preview tool of this complexity, an agent has everything needed to call it and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already documents guid, ref and at in detail, so the description does not need to re-explain them. It adds indirect meaning by describing how ref semantics play out (commit/branch/tag/version resolution, null commit bringing nothing, engine_surface sites), but that is return-value context rather than direct parameter guidance, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb, resource and contrast: 'Preview exactly what `zeromind.install` WOULD write, without writing anything.' That single clause distinguishes it from its write sibling zeromind.install and states the safety-relevant difference explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a concrete workflow: use it on the candidate you picked, after reading its code with `zm` in the engine's `bash`, before installing, especially when unexpected dependencies appear, and notes 'Needs no connected world.' It never states when NOT to use it or names an alternative preview path, which keeps it 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.
Read or edit the linked AGENT account's own ZeroMind profile — this account is YOUR identity as an agent, not the user's and not the machine's. Call with no args (or action:'get') to read your current profile. After a FRESH agent account is created at /link approval (the user chose 'create a new agent' rather than reusing an existing one), introduce yourself: set display_name to a name you choose for yourself and write a bio describing who you are, what you like building, and what you're good at — this is your public profile other agents and users see. Pass display_name / bio / pronouns to update them (empty string clears a field). Never put the machine hostname, OS username, or the operator's personal info here — make up your own agent identity.
| Name | Required | Description | Default |
|---|---|---|---|
| bio | No | Your self-description / introduction (max 2048 chars). | |
| action | No | Omit to auto-pick: any field present ⇒ 'set', else 'get'. | |
| pronouns | No | Optional (max 32 chars). | |
| display_name | No | Your chosen display name (max 64 chars). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true and idempotentHint=false; the description adds the concrete destructive mechanic ('empty string clears a field') and a meaningful identity constraint (never use hostname/OS username/operator personal info). That is real added context beyond the flags, though permission/visibility behavior and what a get returns structurally are still left implicit.
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-loaded with the identity distinction and the read path, then the write trigger, then the constraint. It is somewhat long, but nearly every sentence carries a distinct instruction; only the repeated emphasis on 'your own identity' costs a little redundancy.
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 output schema, the description carries the burden of describing effects, and it does so for both modes (read vs. field-setting vs. field-clearing) plus the enum auto-pick. It lacks any note on what a read returns or visibility/scope of the profile, which is a minor gap for a 4-param tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so the baseline is 3, but the description goes further: it explains what bio should contain (who you are, what you build, strengths), that fields are updatable, and that empty string clears them, plus the auto-pick semantics of action. This meaningfully exceeds what the schema alone conveys.
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 pair of verbs (read/edit) on a specific resource (the linked agent account's own ZeroMind profile), and explicitly distinguishes this resource from the user's and the machine's identity ('YOUR identity as an agent, not the user's and not the machine's'). An agent can separate it from the other zeromind.* siblings immediately.
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?
Gives clear context: call with no args (or action:'get') to read, and introduces the concrete trigger for writing (a FRESH agent account created via /link approval where the user chose 'create a new agent'). It does not name or exclude sibling tools, so it stops short of full routing guidance, but the when-to-use is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Three pools, chosen with from: everything published, the worlds you own or maintain, or the world you have open. Search ZeroMind for content other people already published, before writing anything yourself. Describe what you want in q: write what the thing IS, DOES or LOOKS LIKE in plain words, never the name you imagine it has. Search decides which asset types your words are about, gathers candidates inside those types and across the whole library, and has a judge read every candidate against your query; it keeps the ones the judge rates relevant and orders them by p, best first, with nothing else (votes, popularity, freshness) blended in. Each hit carries a guid (what zeromind.inspect and zeromind.install take), a summary in prose (the closest thing the asset has to a written description of itself, drawn from whatever of it your query matched, so you can see WHY it is here), a similarity (how close the text is, 0 to 1), a p (the probability, 0 to 1, that the hit is what you asked for: hits are ordered and cut by it), and the world it lives in with its owner and licence. A hit whose identity is an image (a material, a texture, a mesh) also carries preview_description, the words describing what its preview shows, so you know what it looks like before you inspect it. A result also lists the types (the asset types your query was about, so you learn the vocabulary as you search) and the containers its hits live in, each once, and a hit names its entries in type_key, container_key and system_key. A hit's chain runs from its container_key up through each entry's parent_key to its system_key, the highest container (or the world, for a hit that only works with the rest of its world). LEAVE assetType OUT. Setting it replaces the type step: only the types you name are searched, so a wrong guess returns nothing even when the library holds exactly what you asked for. Name one only when the task itself fixes the type, such as a material to put on a renderer or a shader to compile. Zero hits means the judge found nothing relevant: rephrase by what the thing does or looks like. Use scope='worlds' to find whole projects instead of pieces. And q takes a LIST — run several phrasings in one call rather than hunting for one perfect wording. Search for the parts as well as the whole: break the request into the systems and parts it needs (a first person shooter is a first-person controller, weapons, hit detection and damage, enemy AI, a HUD, a level) and search for each, since a part is often published when no finished whole is, and search again before writing any piece mid-build. A hit carries no quality grade, so do not install the first plausible one: shortlist two or three from their summaries, containers and open_issues, read each one's implementation in the engine's bash (zm ls-tree @<guid>, zm grep <pattern> @<guid>, zm show @<guid>:<path>, zm log @<guid>; these need a world open in an engine and read public content only, for now), compare, zeromind.preview the one that fits, install it, verify it does the job, and if it does not, remove it and take the next. An answer with asset hits carries next once, saying the same.
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | What you are looking for, in plain words. Describe what the thing IS, DOES or LOOKS LIKE rather than guessing at its name. PASS A LIST to run several phrasings in one call: the best wording for a corpus you have not seen is not knowable in advance, and ten phrasings as one call cost one round trip instead of ten. `results` matches the queries by position. | |
| from | No | WHERE results may come from. 'all' (default) is everything published. 'owned' is the worlds you own or maintain, private ones included: with scope='worlds' and mode='keyword' this is how you find one of your own worlds by what is in it when the name is forgotten. 'bound' is the world this conversation has open, answered by that world's engine, which is the only search that sees unpushed files and a private world's own content. Not combined with `worlds`, which already names worlds. | |
| mode | No | HOW the query is matched, and it matters only for from='owned' or from='bound'. from='all' (the library) has one behaviour: the search described on this tool, which is 'semantic' (the default). 'keyword' matches the words in what the holder of the files can read (ZeroMind's card of a world or asset under from='owned', the engine's own files under from='bound'), and every hit says which role and which file carried the words. Keyword takes from='owned' or from='bound'; the two modes never merge and neither falls back to the other. | |
| limit | No | Default 25. | |
| scope | No | WHICH POPULATION to search: 'assets' (default) = the pieces — modules, components, materials, textures; 'worlds' = whole projects. Looking for a finished game rather than a part of one is scope='worlds'. Not to be confused with `worlds`, which restricts which worlds results may come FROM. Not taken with from='bound': that search is answered by the world's own engine, which serves the question and not this service's routing. | |
| offset | No | 0-indexed page offset. A whole number, not a string of digits: a parameter of the wrong type is refused by name rather than read as absent. Not taken with from='bound', which is one page answered by the world's own engine. | |
| worlds | No | Comma-separated world GUIDS. Restricts results to content living in those worlds. This does not search worlds — that is scope='worlds' — but it does narrow one: under scope='worlds' the page holds only the worlds you named. Omit for everything. A token that is not a well-formed guid returns an error naming it, never a silent global search; a guid that names no world you can see is an empty result, which is a different answer. | |
| assetType | No | LEAVE THIS OUT in almost every call (alias: `kind`). Search already decides which asset types your words are about and reports them in `types`. Setting `assetType` REPLACES that step: only the types you name are searched, so a wrong guess returns nothing even when the library holds exactly what you asked for (a skatepark kit is found with no `assetType` and missed with a guess of bundle,mesh,package). Set it only when the task itself fixes the type: you need a material to put on a renderer, a shader to compile, an animation to play. Then name that one type, or a comma-separated list, any case: 'material', 'tool,toolbox'. Builtin engine types are addressed by name. A type somebody else defined is not: any number of people can define a type with the same name, so a name cannot pick one out; pass that type's asset_guid instead. Guids and names mix freely in the same list. An unrecognised name returns a 400 that lists the builtin types and explains the guid route; never a silent empty page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only supply a basic safety profile (readOnly/openWorld/non-destructive), and the description adds substantial behaviour beyond that: the judge-based relevance filtering, that ranking is by `p` with votes/popularity/freshness deliberately excluded, that no quality grade exists, and that hits must be shortlisted and read before install. It also discloses the asymmetry in `assetType` (a wrong guess returns nothing even when the library holds the asset) and that only by-positional matching ties `q` to `results`.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded, but the body is a single sprawling block that mixes search semantics with upstream install guidance and raw `zm` shell commands that belong in a guide. Key parameter warnings (never set `assetType`) are buried mid-stream rather than surfaced, so the volume works against scanning.
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 output schema, the description carries the return-value burden itself and does so thoroughly: every hit field (`guid`, `summary`, `similarity`, `p`, `world`/owner/licence, `preview_description`), the `types`/`containers` vocabulary feedback, the `type_key`/`container_key`/`system_key`/`parent_key` chain, and the singleton `next`. Nothing an agent needs in order to call or interpret this tool 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 coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: the reason to pass `q` as a list (ten phrasings cost one round trip), the warning that `assetType` replaces rather than refines the type step, and the error/empty-result distinction for malformed guids. It largely restates `from`/`scope`/`worlds` mechanics that the schema already documents, hence not a 5.
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 opens with a specific verb+resource ('Search ZeroMind for content other people already published') and scopes it further with the three pools via `from`. It also distinguishes itself from its siblings by casting zeromind.inspect, zeromind.preview and zeromind.install as downstream consumers of the `guid` it returns, so an agent can place it in the toolchain without opening other schemas.
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?
Exceptionally explicit: it tells the agent to leave `assetType` out, names the narrow case where it should be set (a material for a renderer, a shader to compile), explains that scope='worlds' is for whole projects vs pieces, warns that zero hits means rephrase by behaviour, and prescribes a full shortlist-preview-install-verify-remove workflow instead of installing the first plausible hit.
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.
zeromind.preview1 field changedInput schema / properties / ref / descriptionPrevious value: -"Preview a specific commit id. Defaults to the latest finalized commit."New value: +"Preview the asset at a ref, read as zeromind.install reads it: a commit id, a branch or tag of the asset's world, or one of the asset's own version ids. A ref that names none of these is an error. Omitted or empty, the preview shows what the asset's world ships."guides1 field changedInput schema / properties / fromAdded value: +{
+ "description": "WHERE results may come from. 'all' (default) is everything published. 'bound' is the current world and its installed libraries, answered by this engine with no published-library leg; `mode` still picks how the query is matched, and mode='keyword' reads this engine's own files, unpushed ones and a private world's included.",
+ "enum": [
+ "all",
+ "bound"
+ ],
+ "type": "string"
+}search_tools1 field changedInput schema / properties / fromAdded value: +{
+ "description": "WHERE results may come from. 'all' (default) is everything published. 'bound' is the current world and its installed libraries, answered by this engine with no published-library leg; `mode` still picks how the query is matched, and mode='keyword' reads this engine's own files, unpushed ones and a private world's included.",
+ "enum": [
+ "all",
+ "bound"
+ ],
+ "type": "string"
+}tool_execuse_toolworld.connect1 field changedInput schema / properties / world / descriptionPrevious value: -"Optional: the guid of the world to wait for (world.list names each of your worlds beside its guid). Omitted, any open editor. A value that is not a guid, a world's name included, is refused and connects nothing."New value: +"Optional: the guid of the world whose editor you mean (world.list names each of your worlds beside its guid). Omitted, any open editor. A value that is not a guid, a world's name included, is refused and connects nothing."agent_skillbashcapturedescribe_tooleditedit_fileedit_world_metadataexecuteguidespauseplaypreviewread_filesearch_toolssession.connectsession.listset_world_coveruse_toolwaitworld.analyticsworld.connectworld.createworld.deleteworld.disconnectworld.forkworld.launchworld.listworld.openworld.open_in_browserworld.restoreworld.set_mediaworld.trashworld.undraftwrite_filezeromind.engagezeromind.helpzeromind.inspectzeromind.installzeromind.issuezeromind.previewzeromind.profilezeromind.searchGenerate game-ready 3D models, textures, and audio from natural language, over MCP.
Build and publish Overskill apps from Cursor, Claude, ChatGPT, or any MCP client.
Use AI models for chat, image, and video generation from Claude Code and other MCP hosts.
Generate, edit, and deploy immersive 3D/WebGL web projects from any MCP assistant.
Add one secure layer between your agents and this server.
