open_room

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

With no annotations, the description carries the full burden and does a good job: it discloses that it opens a browser tab, joins a foreign room if a link is supplied, targets the already-joined room otherwise, and reports the connection state plus peer/element counts. It doesn't mention errors or auth, but for this tool that's a minor 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 sentences, front-loaded with the main action, and every sentence adds either the parameter rule or return-value context. No fluff.

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 annotations and no output schema, the description covers the side effect, the conditional parameter behavior, and the return contents. It doesn't cover potential errors or when not to use, but for a single optional parameter tool this is mostly 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?

The schema covers the string parameter, but the description adds the key conditional semantics: omit for current room, provide when server is not in the roomasian, and it gets joined first. This goes 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?

The tool's purpose is immediately clear: 'Open the room on excalidraw.com...' is a specific verb+resource statement. It also positions itself as 'the primary way for a person to watch' the room, which helps distinguish it from sibling tools like room_status or poll_room that serve programmatic monitoring rather than human viewing.

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 gives concrete usage guidance: use it as the primary way to let a person watch live, and only pass a link when the server is in no room or a different room. It does not explicitly name sibling alternatives or exclusion conditions, but the context is clear.

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