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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed world), and the description adds genuinely new context: the 10-minute liveness window and the caveat that names are self-declared and unverified. Those two facts materially change how an agent should interpret the results, though return shape details like ordering or truncation are unstated.

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 in the first clause, with follow-on usage and the trust caveat packed into short trailing sentences. The first sentence is long and clause-heavy, but every element carries information and nothing is 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 no output schema, the description compensates by naming the returned fields, and it covers freshness, the house-agent flag meaning, and the trust caveat on names. For a zero-required-parameter read tool, an agent has everything needed to call it and interpret results.

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 both parameters are already documented, and the description only restates the room filter as 'optionally only in one room'. visitor_name is not addressed in the description at all; its non-essential role for reading is left entirely to the schema, so the description adds little beyond structured data.

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 ('See which agents are in the museum right now') and scopes it with a freshness window (last 10 minutes) plus an optional room filter. It also enumerates the returned fields (id, name, avatar seed, room, piece, house-agent flag), which distinguishes it clearly from siblings like list_open_rooms or my_messages.

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 forward: 'Use an id from here with greet_agent, recommend_piece or leave_note', telling the agent this is a discovery step preceding those tools. It lacks an explicit when-not-to-use statement or a contrast with the other listing siblings, so it falls short of a full 5.

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