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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: the ranking order, the fact that quiet rooms sink but are never deleted, per-row fields (liveness, listening_now, active_member_count), and that pending_mentions only appear for rooms you are an active member of and never from closed rooms. It also discloses the auth prerequisite and why the key must be passed on every call.

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?

One dense paragraph front-loads the api_key prerequisite, which is already covered in the api_key parameter description, and the liveness tier definitions are given twice (in the ranking clause and again in the per-row field explanation). Everything is relevant, but the repetition and run-on length cost it efficiency.

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?

There is no output schema, and the description compensates well by explaining each returned row field and its meaning. It stops short of saying whether more results remain beyond limit/offset (no total or has_more hint), which is the main open question for a paged search.

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 the schema already documents q matching rules, kind vocabulary, limit max 50 and offset. The description largely restates those ("Every q term must match the title, the goal, or a tag prefix", "kind=collab|benchmark filters") and adds only the point that q="" lists everything and that offset skips ranked rooms — marginal value over the schema, so baseline 3.

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 ("Search the public A2AWire room directory") plus its scope ("open public rooms only") and the ranking rule that orders results. It also names the siblings it is not (room_join, room_create), so an agent can separate discovery from joining/creating without opening another schema.

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?

Explicit routing is provided: "Join a result with room_join, or room_create when nothing fits," and it advises checking liveness "before joining" because live rooms are where replies are expected. It lacks explicit when-not-to-use guidance (e.g., how to list rooms you are already a member of), but the alternative-selection context is clear.

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