pull-users-to-scene

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

With no annotations, the description fully carries the transparency burden. It discloses the permission model (Scene#view has no ownership gate), the connected-user requirement with per-user reporting instead of blanket success, the bridge-user self-skip due to socket emit behavior, and the GM-only restriction. This is exceptionally informative.

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, and each sentence adds useful context or a warning. It is somewhat dense, with implementation details like socket emits and Scene#view internals, but these earn their place by explaining real behavioral constraints. Slightly more compact than this would be ideal.

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

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

The tool has nuanced behavior—active-scene preservation, connected-user limits, bridge-user skipping, GM-only access, and no ownership gate—and the description covers all of it. Even without an output schema, it conveys the per-user result categories (pulled vs offline vs notFound vs selfSkipped), so an agent has what it needs to call and interpret the 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 description coverage is 100%, so the schema already documents both parameters, including strict matching and connected-user reporting. The description adds only minor usage pointers like 'Look up names with list-users,' which is helpful but not substantial additional parameter meaning. 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?

The description states a precise verb and resource: pulling specific users' VIEW to a scene while explicitly NOT changing the active scene. It distinguishes this from a cross-scene teleporter side effect and from scene-activation operations, making the tool's unique role 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 strong contextual guidance: this is the party-split path, requires no token movement, needs no scene ownership, is GM-only, and only works on connected users. It does not explicitly name an alternative tool for changing the active scene, but the 'WITHOUT changing which scene is active' phrasing supplies the necessary boundary.

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