clients module provides tools to search, retrieve, create/link, and
inspect client profile access within the company scope.
Available Tools
Home branches
list_client_home_locations lists eligible company home branches within your
current staff location scope. Optional query searches names; page starts at
1 and limit defaults to 25 (maximum 100). The result contains locations
with stable locationId and name, plus page, limit, total and hasMore.
get_client_home_location accepts clientId and returns the current assignment
with hasHomeLocation, homeLocationId and homeLocation (locationId, name).
An unset assignment has hasHomeLocation: false; empty optional fields may be
omitted from compact responses.
update_client_home_location requires clientId, homeLocationId (an eligible
branch ID, or explicit null to clear it), a nonblank reason of 3–500 characters,
userConfirmed: true and an idempotency key. Review the target member and branch
with the user before confirming. The result includes changed and
hasHomeLocation. Only the home branch changes. The member’s postal address,
signup location, coach, lifecycle and bookings are separate.
Reads require current members.view permission; updates require
members.update, access to the member and destination branch, and the explicit
update_client_home_location write grant. These checks also apply to retries.
Branches must belong to the connected company and be eligible for member
assignment. Archived or unavailable branches cannot be assigned.
For multiple members, use the optional customer imports module.
Member status automation and history
get_member_status_automation reads the effective company rules. It returns
rules as an array of { event, action } and preserveManualStatuses.
The seven events, all allowed actions and company defaults are documented in
company status automation.
update_member_status_automation accepts a partial statusAutomation object
and/or a boolean preserveManualStatuses. Omitted rules and other settings
are preserved. It returns the effective rules array and protection flag.
Changes apply to future lifecycle events without updating existing members in
bulk. An explicit grant for this write tool and an idempotency key are required.
The connection’s owner must also retain active company access and
access.settings.update; standard authorization mode requires an Admin.
The tool grant does not replace this company permission check.
update_client_lifecycle requires clientId plus at least one of
relationshipStatus (trial, active, paused, inactive),
portalAccessStatus (enabled, disabled, suspended) or
relationshipStatusMode (automatic, manual). A status edit defaults to
manual protection; automatic mode resumes company rules for future events.
It returns a lifecycle object with client ID, relationship status, mode,
member status and portal access. Protected relationship states require their
dedicated workflows. Existing client access rules apply. An explicit grant
for this tool and an idempotency key are required.
list_client_status_history requires clientId and accepts page (default 1)
and limit (default 50, maximum 100). It returns current relationshipStatus
and relationshipStatusMode, pagination metadata, and history ordered newest
first. Entries contain fromStatus, toStatus, source (automatic, coach,
integration, system), event, UTC changedAt and nullable
changedByCoachId. Mode changes may retain the same status. Earlier changes
may have no recorded history.
Client search and detail also return relationship.statusMode.
search_clients
Search the company’s client list by name or email, optionally filtered by tag
or home location. Returns paginated client summaries including
relationship.tags and relationship.homeLocation.
- Type: Read-only
- Important Input Fields:
query(string, optional): Search string matched against first name, last name, or email. Max 200 chars.relationshipStatus(string, optional): Filter by status (e.g.active,invited,inactive).tag(string, optional): Tag name, exact and case-insensitive (e.g.testaccount).homeLocationId(string, optional): Only clients with this home location.page(integer, optional): Page number, starting at 1.limit(integer, optional): Page size, max 50.
get_client
Retrieve a client’s complete profile, including tags and home location.
relationship.homeLocation is the company location the member belongs to;
location is the member’s postal address. followUp contains the follow-up
date, its source (manual, retention or unknown) and the
assignedCoach, or null values when no follow-up is set.
- Type: Read-only
- Important Input Fields:
clientId(string, required): Unique client identifier.
create_client Write
Create a new client profile or link an existing account by email to the company.
- Type: Write
- Important Input Fields:
firstName(string, required): Client first name. Min 2 chars.email(string, required): Client email.lastName(string, optional): Client last name.inviteByEmail(boolean, optional): Whether to send invite email.homeLocationId(string or null, optional): Eligible company home branch. Omitting it preserves the existing create/link behavior. Supplying it also requires currentmembers.createpermission and member/location scope. An existing company relationship must be readable; use the dedicated relationship workflow for a rejected or removed relationship first.
inspect_client_data_access
Inspect stored external-data grants and company connection status for a client.
External-data grants are reserved for separately authorized sources such as
future wearable integrations. An empty list does not block company-owned
nutrition or measurements and is separate from the connection’s health consent.
- Type: Read-only
- Important Input Fields:
clientId(string, required): Unique client identifier.
get_retention_planner_rules
Retrieve the retention planner rules: conditions, suppression settings and
configured actions (follow-up, todo, coach notification, member email, member
chat). Email and chat bodies are not returned. Returns the default rules with
isDefault: true when the company has not saved settings.
- Type: Read-only
- Important Input Fields:
enabledOnly(boolean, optional): Only return enabled rules.
list_retention_members
List members who currently match the retention planner rules (risk list), read
from the precomputed retention projection. Returns matched rules with severity
and priority, follow-up date and cheap activity counters. Member emails are not
returned. freshness.status shows whether the projection is ready.
- Type: Read-only, paginated
- Important Input Fields:
ruleId(string, optional): Only members matching this rule.severity(string, optional):watch,risk,highRiskorlost.page,limit(integer, optional): Pagination (limit max 50).
list_retention_approvals
List retention outreach approvals (member emails and chats waiting for coach
review), newest first. Only the email subject is returned, never the body.
- Type: Read-only, paginated
- Important Input Fields:
status(string, optional):pending(default),sent,rejected,failed,skippedorall.ruleId(string, optional): Only approvals from this rule.page,limit(integer, optional): Pagination (limit max 50).
list_client_field_catalog
List the company’s member tags (with member counts) and the active custom
client field definitions (key, label, type, required, select options).
- Type: Read-only
- Important Input Fields: none.
update_client_custom_field_values
Update one or more values on an existing member using clientId and
customFieldValues: [{ key, value }]. Requires a separate write grant and an
idempotencyKey. Only existing, active, non-hidden fields enabled for the
client page can be changed. Values are validated against the field type,
configured options and validation rules. Automatic numbering fields are
read-only. Other values are preserved; null or an empty string clears a value.
For a newsletter opt-out checkbox, use its existing field key with the boolean
value true (the displayed label may be “Yes”). The tool changes the member
field; it does not unsubscribe the member in an external mailing system.
clientId and updatedKeys. Unknown or non-writable
fields and invalid values fail validation. Use list_client_field_catalog to
find existing definitions and get_client to read the resulting member values.
update_client_tags
Add or remove existing company tags for one accessible member. Requires the
clients module, its own update_client_tags write grant, current member update
permission and an idempotencyKey. This tool is available to company/coach
connections. It does not create tags.
clientId: Member ID.assignTagIdsand/orremoveTagIds: At least one non-empty array of tag IDs, with at most 100 IDs per array. Get tag IDs fromlist_client_field_catalog.idempotencyKey: Unique key for this change. Reuse it only for an exact retry.
clientId; read the resulting tags with get_client.
Changes may emit a client.updated webhook. Normal MCP connection rate limits
apply. Existing connections need explicit approval of the new write grant.
list_registration_requests
List member registration requests awaiting coach approval (or rejected), newest
first, with signup location. Placeholder emails are returned as an empty string.
- Type: Read-only, paginated
- Important Input Fields:
status(string, optional):pending(default) orrejected.page,limit(integer, optional): Pagination (limit max 50).
decide_registration_request Write
Approve or reject one pending member registration request from list_registration_requests, like the dashboard. Approve activates the member; reject declines the sign-up. reviewMessage is stored with the decision. Get explicit coach confirmation first.
- Type: Write (requires
userConfirmed: trueand the write-tool grant) - Input Fields:
requestId(string, required)decision(string:approve,reject, required)reviewMessage(string, optional)idempotencyKey(string, optional)
create_client_tag Write
Create a new company member tag (name and optional hex color like #1E88E5) that update_client_tags can then assign. Get explicit coach confirmation first.
- Type: Write (requires
userConfirmed: trueand the write-tool grant) - Input Fields:
name(string, required)color(string, optional)idempotencyKey(string, optional)
list_client_custom_fields
List the full company shared member field library, including hidden and inactive definitions, labels, validation, usage and automatic numbering settings. Does not return member values. Page numbers start at 1; default limit 10, maximum 100.
- Type: Read
- Input Fields:
page(integer, optional)limit(integer, optional)
create_client_custom_field Write
create one company shared member field definition. Keys cannot be renamed. Updates merge supplied properties and nested labels, usage and sequence settings. Deleting a used field hides and deactivates it while preserving all member values; unused fields are removed. Generated values remain read-only. Requires a separate explicit write grant and idempotency key.
- Type: Write (requires
userConfirmed: trueand the write-tool grant) - Input Fields:
field(object, required)idempotencyKey(string, optional)
update_client_custom_field Write
update one company shared member field definition. Keys cannot be renamed. Updates merge supplied properties and nested labels, usage and sequence settings. Deleting a used field hides and deactivates it while preserving all member values; unused fields are removed. Generated values remain read-only. Requires a separate explicit write grant and idempotency key.
- Type: Write (requires
userConfirmed: trueand the write-tool grant) - Input Fields:
key(string, required)field(object, required)idempotencyKey(string, optional)
delete_client_custom_field Write
delete one company shared member field definition. Keys cannot be renamed. Updates merge supplied properties and nested labels, usage and sequence settings. Deleting a used field hides and deactivates it while preserving all member values; unused fields are removed. Generated values remain read-only. Requires a separate explicit write grant and idempotency key.
- Type: Write (requires
userConfirmed: trueand the write-tool grant) - Input Fields:
key(string, required)idempotencyKey(string, optional)
decide_retention_approval Write
Approve or reject one pending retention planner approval from list_retention_approvals. Approve runs the proposed action exactly as proposed (for example a member message or email); edit the proposal in the dashboard first if it must change. Reject needs a reason. An approval that is no longer pending returns status skipped. Show the coach the member and the exact action, and get explicit confirmation first.
- Type: Write (requires
userConfirmed: trueand the write-tool grant) - Input Fields:
approvalId(string, required)decision(string:approve,reject, required)reason(string, optional)idempotencyKey(string, optional)
Natural Language Examples
- “Find Jane Doe in my company’s client list.”
- “Create a new client named Tom Hardy with email tom.hardy@example.com.”
- “Inspect the company connection and external-data grants for client 64b64c0f2f5f4c0012345678.”