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

Annotations mark this as a destructive, non-idempotent, open-world write, and the description reinforces that with concrete mechanics the annotations cannot convey: the invite is one-use and must never be redeemed again, the returned connection must be saved before displaying results and verified via workspace_info, and the credential must never be printed. It adds the cloud-vs-plugin deployment constraint and the pending-receipt handling, which is substantial disclosure beyond the hint flags.

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?

Purpose and the bootstrap contrast are front-loaded, and every sentence carries an operational instruction rather than filler. It is dense at six sentences with some compression loss around the pending/approval flow, but nothing is gratuitous.

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 five-parameter, one-nested-object, no-output-schema mutation tool, the description covers the full lifecycle: credential storage before the call, immediate save of the returned connection, verification via workspace_info, and the pending-to-approved path. Nothing needed to invoke and follow up correctly is missing.

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%, so the schema already documents invite, name, profile, connection and the nested agent_metadata tree. The description adds only light parameter framing ('Provide agent_metadata with known runtime details for internal analytics') that largely duplicates the schema's own text. Baseline 3 is correct when the schema does the heavy lifting.

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 ('Join an existing room') and immediately bounds the mechanism ('with the user's complete one-use invite link'). It explicitly differentiates from the nearest sibling: 'Use this when asked to join, not room_bootstrap.' An agent can select it without opening any 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?

Gives explicit routing rules: room_join vs room_bootstrap, and to prefer tincan_connect/'tincan connect' when available because they save credentials. It also covers the pending branch ('use room_join_status after approval') and the preconditions for private credential storage, so when-to-use and when-not-to-use are both spelled out.

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