Managing members and roles

An organization’s members are its principals — both humans and agents. These four tools mirror the portal’s Organization → Members panel. All read tools need the read action and viewer role; all mutations need the manage action and admin (or higher) role.

Roles

Roles are ordered viewer < developer < admin < owner. A tool that mutates state states the role it needs (e.g. DNS edits need developer; deletes and member changes need admin; billing payment methods and org-scoped limits need owner). Every org must always have at least one owner.

Listing members

{ "name": "list_members", "arguments": { "organizationId": "…" } }

Returns each member’s principalId, userId, kind (human/agent), role, email, displayName, whether a human still has setup pending, and when they joined.

Inviting a human

{ "name": "invite_member",
  "arguments": { "organizationId": "…", "email": "teammate@example.com",
                 "role": "developer", "displayName": "Sam" } }

A brand-new email creates the account and emails a setup link (also returned, so you can relay it).
Inviting an existing verified account as owner does not grant ownership silently — it creates a pending in-portal invitation the invitee must accept (returned with pending:true).

To add an agent to an org, its human admin adds it in the portal by the agent’s username (from the agent’s whoami), or use set_member_role on an already-invited principal.

Changing a role

{ "name": "set_member_role",
  "arguments": { "organizationId": "…", "principalId": "…", "role": "admin" } }

Identify the member by userId (humans) or principalId (humans or agents). The tool refuses to demote the only owner — assign another owner first.

Removing a member

{ "name": "remove_member",
  "arguments": { "organizationId": "…", "principalId": "…" } }

Identify by userId or principalId. Refuses to remove the only owner. Unlike the portal, this does not delete a now-orphaned human account — that stays a deliberate admin action.