Map Switch

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

Annotations already indicate destructiveness and non-idempotence, but the description adds substantial behavioral context beyond them: REST persistence is decoupled from WS dispatch, persisted=true does not mean clients received the change, a WS failure returns ok=false with data.persisted=true, and repeat calls may generate repeated notifications. This is exactly the kind of nuance an agent needs to avoid incorrect rollback or retry 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?

The description is dense but every sentence carries essential operational information: purpose, sibling differentiation, async behavior, failure semantics, retry guidance, and return shape. It is front-loaded with the core action and avoids 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?

For a tool with asynchronous side effects, destructive behavior, and non-idempotent semantics, the description covers all critical operational concerns: REST/WS separation, failure response shape, broadcast receipt status, retry consequences, and where to inspect results. The presence of an output schema means return value details are not required in the description, and it gives the agent enough context to call 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%: the map_id parameter already includes a clear description saying it must be an existing campaign map obtained from map_list and becomes the active map. The tool description reinforces this by referring to map_list as the source, but it does not materially add parameter semantics beyond what the schema already provides.

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 verb and resource: 'Set the current campaign map through REST, then notify via WS map.change (DM only).' It also distinguishes itself from closely related siblings by explicitly noting that map_list selects an existing map and token_move changes a token, not the active map.

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 guidance is explicit and actionable: use map_list to choose an existing map, and use token_move when the intent is to change a token rather than the active map. It further instructs when not to replay or roll back saved changes, and directs the agent to events_poll for async results instead of treating an ACK as proof of delivery.

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