mesh_join_realm

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

No annotations exist, so the description carries full responsibility—and it delivers: it discloses the two-step asynchronous nature, background polling, filesystem storage under ~/.config/mesh, issuance of credentials/UCAN, the already-joined behavior, and the older-realm fallback where no UCAN is issued. Side effects and statefulness are clearly visible.

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?

Front-loaded with the core purpose, then flows naturally into the mechanism, storage, polling, and edge behaviors. Despite the density, every clause adds information; there is no fluff or repetition.

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 side-effecting, async, stateful operation with no output schema, the description covers what an agent needs: the initial return value, how to poll, where state persists, what gets issued, how identity UI reflects it, and the legacy-realm exception. Nothing critical is left to guesswork.

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 already describes wait_seconds well (0 returns immediately, session lasts 10 minutes), so the baseline is high. The description adds value by explaining how wait_seconds is used in a later call to collect an already-started join's outcome, which is not fully obvious from the schema alone.

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 action ('Join the io.macula realm'), identifies the agent as the subject, and explains the binding of server identity to a person's account. The flow and artifacts issued (org identity, realm certificate, membership UCAN) make the tool's purpose unmistakable even without opening the 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 clear operational context: first call returns a link, subsequent calls with wait_seconds retrieve the outcome, and already-joined members get the membership back. It does not explicitly name alternatives or when not to use this tool, but the realm-joining flow is distinct enough among the siblings that an agent can route correctly.

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