Playtest control

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

Annotations declare destructiveHint=true, and the description elaborates on this: 'push ... ephemeral, not undoable' and 'replace (default true) removes a same-name, same-class sibling first (never Terrain, the camera, a character)'. It also discloses the restart cost (~3 s), state loss ('loses play-DM state'), persistence semantics ('persist: kept by the bridge, re-installed whenever that DM appears in a later playtest'), and async behavior ('Slow actions return {job_id, status:"running"} after wait_ms; use `job`'). This goes well beyond the annotations, which only say destructiveHint=true. The only minor gap is that it doesn't explicitly state that start/stop are also destructive in the sense of ending a running playtest, but the 'Keep ONE playtest alive' warning covers that.

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

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

The description is dense but well-structured: it opens with the most important constraint ('Keep ONE playtest alive'), then groups actions with their parameters in a compact notation. Every sentence carries information: the restart cost, the no_peer workaround, the predicate semantics, the persist behavior, the push replacement rules, and the async job handle note. It loses one point because the density makes it somewhat hard to parse at a glance – the action-parameter groupings are packed into a single paragraph without line breaks, and an agent might need to re-read to extract the exact parameter list for a given action. Still, it is far from verbose and front-loads the critical warning.

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

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

For a tool with 23 parameters, no output schema, and a complex multi-action surface, the description covers the essential behavioral context: what each action does, which parameters apply, what the return values look like (e.g., {running, mode, players, peers, started_ms}), and the async job handle pattern. It also covers edge cases like no_peer, persist, and replace. It doesn't fully document every return shape for every action (e.g., status returns {running, mode, players, peers, elapsed_s, controllers} but stop only shows {stopped_ms}), and it doesn't explain the `args` parameter's role in run_until beyond 'available to the program as ARGS'. Given the tool's complexity, these are minor gaps; the description is remarkably complete for a 23-parameter 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 description coverage is 96%, so the schema already documents most parameters. The description adds meaning by grouping parameters with their actions (e.g., 'start {mode: play|run|multiplayer, players}', 'run_until {dm, predicate | predicate_file, timeout_ms ≤ 120000, interval_ms, args}'), which clarifies which parameters apply to which action. It also adds constraints not fully in the schema, such as 'players (1-8, default 2)' and 'timeout_ms ≤ 120000'. The description doesn't repeat every schema description, but it adds the action-parameter mapping that the flat schema lacks. A 4 is appropriate because the schema does most of the work, but the description adds meaningful grouping and defaults.

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 clear verb and resource: 'Control the live playtest and the in-engine runtime.' It then enumerates each action (start, stop, status, run_until, install, uninstall, list, hotpatch, push) with its specific purpose, which distinguishes it from sibling tools like observe, look, run, input, events, skills, job, and cloud. The scope is unambiguous: this is the tool for managing playtests and the live DM runtime, not for observing or running code in other contexts.

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 provides explicit usage guidance: 'Keep ONE playtest alive; a restart costs ~3 s and loses play-DM state.' It also gives conditional guidance for multiplayer ('no_peer: turn on "Load User Plugins In Run Modes" / install the plugin'), for run_until ('Luau predicate evaluated in-engine each Heartbeat until truthy'), and for push ('replace (default true) removes a same-name, same-class sibling first'). It names alternatives implicitly by listing all actions and their parameters, and the sibling list shows this is the only playtest control tool. The description also warns about slow actions returning job handles, which tells the agent when to expect async behavior.

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