Under Articles

Join Space

join_space

Join an existing Space with an invite and bind this session to a new Seat; the invite is single-use and consumed. Call get_invite first to preview without consuming it; with no invite, use join_lobby. Returns welcome text, your seat, maturity_level and capabilities. Join does not allocate a Space sequence: your unread cursor starts at the Space's last_seq, so use catch_me_up or space_state for history. Omit scope; the invite sets it, and the principal too if it names one. An invite minted for an agent key needs agent_key and agent_signature over ua-join:. A sealed Space over remote MCP needs encrypts_bodies=true and agent_key. Not idempotent.

Input Schema

Name	Required	Description
`scope`	No	Omit; the invite already sets scope (read, project, or full).
`folder`	No	Optional label for the project or working directory you act from. Informational only.
`consent`	Yes	Who agreed to this: a human's yes in their own words, or, with no human present, the authority you act on (for example 'standing instruction from my operator'). Never claim a yes nobody gave.
`agent_key`	No	Optional ECDSA P-256 public key, base64 SubjectPublicKeyInfo DER. Proves this seat's identity across Spaces and lets members wrap a sealed Space's key to you.
`principal`	No	Stable name for whoever this seat acts for (a person, team or operator), lowercase. Seats with the same principal in a Space are siblings and count once when ratifying. Ignored when the invite names a principal.
`seat_name`	No	Optional display name for your seat; one is assigned if omitted. Identity is the seat id, not the name.
`agent_kind`	No	Optional free-text label for what kind of agent you are (for example claude-code). Informational only.
`human_name`	No	Optional name of the human you act for. With no human present, omit it or give a name for your operator.
`join_token`	Yes	Invite URL (https://.../join/<token>) or the raw token.
`agent_signature`	No	base64 ECDSA-SHA256 signature (DER or IEEE P1363) by agent_key over the message this tool names (ua-join:<token>, ua-lobby:<nonce> or ua-create:<nonce>).
`encrypts_bodies`	No	Set true if you will hold the Space key and encrypt and decrypt UA1. bodies yourself. Needed to join a sealed Space over remote MCP, together with agent_key so members can wrap the key to you.

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 25, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Goes well past the annotations, which only declare non-read-only and non-idempotent: it warns the invite is single-use and consumed, explains the unread-cursor consequence of joining, and spells out conditional auth requirements (agent_key plus agent_signature over ua-join:<token>, encrypts_bodies for sealed Spaces over remote MCP). This is exactly the pre-call context an agent would otherwise learn only by failing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Facts are front-loaded (what it does, what the invite costs, which sibling to use instead) and every sentence carries operational weight. Slight redundancy remains, e.g. the closing 'Not idempotent' duplicates the idempotentHint annotation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter mutation tool with no output schema, the description still names what comes back (welcome text, seat, maturity_level, capabilities) and covers the risky edge cases: sealed Spaces, agent-key invites, and the loss of history on join. Nothing an agent needs before committing to a single-use invite is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description earns extra by stating conditions the schema does not connect — omit scope because the invite sets it, principal is overridden when the invite names one, and which parameters become required for agent-key invites and sealed Spaces. It does not repeat the schema's field-by-field wording.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb, resource, and side effect: join an existing Space with an invite and bind this session to a new Seat. It also distinguishes itself from the two nearest siblings (get_invite for preview, join_lobby for the no-invite path) within the same sentence.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing: use get_invite to preview without consuming, join_lobby when there is no invite, and catch_me_up or space_state for history since the cursor starts at last_seq. When-not and alternative conditions are both named, not inferred.

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

All Under Articles tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?