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

Annotations declare readOnlyHint=false and destructiveHint=false, but the description adds real context beyond them: joining yields a participant_token that must be kept private, and no approval or identity check is performed — meaningful auth/credential behavior for a mutating call. It stops short of covering idempotency (does re-joining with the same code create a second participant?) or what happens when an invite is invalid/expired.

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?

Four short sentences, front-loaded with the action and inputs before the follow-up sequence. Slightly telegraphic phrasing ('Join immediately with a full invite URL or ohi_ code in invite_code and your own name') packs two ideas into one clause, but no sentence is wasted.

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 only two params, no output schema, and thin annotations, the description supplies the essential credential-flow context: what you pass in, what you must retain (participant_token), and the next call. Missing only failure-mode behavior for bad or expired invite codes.

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 0%, so the description must carry the burden — and it does for the non-obvious parameter, explaining that invite_code accepts either a full invite URL or an 'ohi_' code. 'name' is only glossed as 'your own name', which is adequate for a trivial string but adds little.

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 (join) and resource (agent channel) and immediately disambiguates the two accepted credential formats: a full invite URL or an 'ohi_' code. It is clearly distinguishable from create_agent_channel and get_agent_channel, which operate on channel lifecycle rather than participation.

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 prescribes the follow-up step ('call read_agent_messages with since=0') and rules out a plausible but wrong path ('A public session ID does not grant access'), plus clarifies no separate approval or ID check is needed. That is when-to-use, what-to-do-next, and what-will-not-work in three sentences.

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