Relativity

Generate a new usage report. Report generation is asynchronous — the returned report will have status "Scheduled". Use relone_usage_wait_for_report to poll until it reaches "Completed". All field GUIDs must belong to the same reportType (Workspace or User). PERMISSION NOTE: Returns 403 unless the OAuth client's Context User is in a group with 'View Instance-wide Usage Reports' (or 'View Client Domain Usage Reports') under Admin Operations, plus 'Management Console' + 'Usage Reports' under Tab Visibility. System Admin alone is not sufficient — this permission must be explicitly granted.

relone_usage_generate_report

Get field definitions for a specific object type. Use relone_list_choices for choice-type fields to see available values. Returns a paginated envelope with TotalCount (authoritative total), an Items page, ActiveFilters, and ProjectionUsed.

relone_get_fields

Get details of a specific usage report by ID. Returns status (Scheduled, InProgress, or Completed), name, date range, fields, type, and creation timestamp. PERMISSION NOTE: Returns 403 unless the OAuth client's Context User is in a group with 'View Instance-wide Usage Reports' (or 'View Client Domain Usage Reports') under Admin Operations, plus 'Management Console' + 'Usage Reports' under Tab Visibility. System Admin alone is not sufficient — this permission must be explicitly granted.

relone_usage_get_report

Retrieve available metadata fields (origins and metrics) for building usage reports. Each metric has a GUID, name, description, valueType, reportType (Workspace or User), and isDefault flag. Use the GUIDs in the fields array when generating a report. PERMISSION NOTE: Returns 403 unless the OAuth client's Context User is in a group with 'View Instance-wide Usage Reports' (or 'View Client Domain Usage Reports') under Admin Operations, plus 'Management Console' + 'Usage Reports' under Tab Visibility. System Admin alone is not sufficient — this permission must be explicitly granted.

relone_usage_get_metadata

Get paginated row-level data from a finished usage report. The response contains a Fields array (metric GUIDs as column headers) and an Items array (rows of values). The report must have status "Completed" — call relone_usage_wait_for_report first if just generated. PERMISSION NOTE: Returns 403 unless the OAuth client's Context User is in a group with 'View Instance-wide Usage Reports' (or 'View Client Domain Usage Reports') under Admin Operations, plus 'Management Console' + 'Usage Reports' under Tab Visibility. System Admin alone is not sufficient — this permission must be explicitly granted.

relone_usage_get_report_details

Get details of a specific workspace by ID. Returns workspace name, status, matter and client references, and creation/modification timestamps.

relone_get_workspace

Get progress of an asynchronous workspace-create job returned by relone_create_workspace. JobState transitions NEW → IN_PROGRESS → COMPLETED (or ERROR). On COMPLETED, WorkspaceId is populated — call relone_get_workspace for full workspace details. Poll every 30–60 seconds. Workspace creation typically completes in 5–10 minutes.

relone_get_workspace_create_job

Grant a security group access to a workspace. In Relativity, workspace access is controlled through groups — users are members of groups, and groups are granted access to workspaces. Use relone_list_groups to find the group Artifact ID, then use this tool to add it to a workspace. Uses the Permission Manager Kepler service — caller needs Manage Workspace Permissions rights.

relone_add_workspace_group

Get available values for a choice field. Returns a paginated envelope with TotalCount (authoritative total), an Items page, ActiveFilters, and ProjectionUsed. Use the field name from relone_get_fields results as the fieldName parameter.

relone_list_choices

List legal clients configured in the Relativity aiR instance. Clients are the top-level organizational entity — every Matter belongs to a Client, and every Workspace belongs to a Matter. Use this to find or verify a Client before creating a Matter. Returns a paginated envelope with TotalCount (authoritative total), an Items page, ActiveFilters, and ProjectionUsed. Queries admin workspace (-1).

relone_list_clients

List the security groups a user belongs to. Use relone_list_users to find the user Artifact ID first, then call this tool with that ID. Returns a paginated envelope with TotalCount, an Items page (each Item exposes ArtifactId, Name, and any other fields requested via projection), Start, and Truncated. Backed by the Group Manager Kepler service's groups/query-by-user/{userId} endpoint, which is the canonical way to ask this question — there is no general-purpose 'groups this user is in' query in Object Manager. Membership changes from relone_add_user_to_group / relone_remove_user_from_group are eventually consistent and may take several minutes to appear in the results here.

relone_list_user_groups

List legal matters (cases) configured in the Relativity aiR instance. A Matter belongs to a Client and is required when creating a new Workspace — you must provide the Matter's Artifact ID to relone_create_workspace. Use this to find the correct Matter ID before workspace creation. Returns a paginated envelope with TotalCount (authoritative total), an Items page, ActiveFilters, and ProjectionUsed. Queries admin workspace (-1).

relone_list_matters

List object types in a workspace. Use the Artifact Type ID from Items with relone_get_fields to inspect a type's fields. Returns a paginated envelope with TotalCount (authoritative total), an Items page, ActiveFilters, and ProjectionUsed.

relone_list_object_types

List security groups on the Relativity aiR instance. Groups control access to workspaces and objects — users are assigned to groups, and groups are granted permissions on workspaces. Use this to find groups before assigning workspace access with relone_add_workspace_group. Returns a paginated envelope with TotalCount (authoritative total), an Items page, ActiveFilters, and ProjectionUsed. Common built-in groups include 'System Administrators' and 'Everyone'. Queries admin workspace (-1).

relone_list_groups

List all existing usage reports for the tenant. The endpoint is not paginated — all reports are returned in a single call, so TotalCount equals the number of Items. PERMISSION NOTE: Returns 403 unless the OAuth client's Context User is in a group with 'View Instance-wide Usage Reports' (or 'View Client Domain Usage Reports') under Admin Operations, plus 'Management Console' + 'Usage Reports' under Tab Visibility. System Admin alone is not sufficient — this permission must be explicitly granted.

relone_usage_list_reports

List user accounts on the Relativity aiR instance. Use this to find users when setting up workspace access, verifying team membership, or checking who has admin privileges. Returns a paginated envelope with TotalCount (authoritative total), an Items page, ActiveFilters, and ProjectionUsed. Queries admin workspace (-1). Filter by name or email using the condition parameter (e.g., condition: "'Email Address' LIKE '%@relativity.com'"). Use the projection parameter to request admin-relevant fields like Enabled, First Name, or Last Name.

relone_list_users

List the users that are members of a security group. Use relone_list_groups to find the group Artifact ID first, then call this tool with that ID. Returns a paginated envelope with TotalCount, an Items page (each Item exposes ArtifactId, Full Name, Email Address), Start, and Truncated. Backed by the Group Manager Kepler service's groups/{groupId}/query-members endpoint. Membership changes from relone_add_user_to_group / relone_remove_user_from_group are eventually consistent and may take several minutes to appear in the results here.

relone_list_group_users

List the security groups that currently have access to a workspace. Use this to audit workspace access, verify a group was added, or check which teams can see the workspace. Returns a paginated envelope with TotalCount (authoritative total), an Items page, ActiveFilters, and ProjectionUsed.

relone_list_workspace_groups

List workspaces that can be used as templates when creating new workspaces. In Relativity, any existing workspace can serve as a template — creating a workspace from a template clones its structure, views, layouts, fields, and applications into the new workspace. Use the Artifact ID from the Items as the templateId parameter in relone_create_workspace. Returns a paginated envelope with TotalCount (authoritative total), an Items page, ActiveFilters, and ProjectionUsed. Note: template-based workspace creation can take 5+ minutes for DB restore and permissions setup.

relone_list_workspace_templates

List workspaces on the connected Relativity aiR instance with optional name filtering. Returns a paginated envelope with TotalCount (authoritative total), an Items page, ActiveFilters, and ProjectionUsed.

relone_list_workspaces

Revoke a security group's access to a workspace — the inverse of relone_add_workspace_group. All members of the group will lose access to the workspace. Uses the Permission Manager Kepler service — caller needs Manage Workspace Permissions rights. Server-side idempotent: removing a group that doesn't currently have access is a no-op.

relone_remove_workspace_group

Remove a user from a security group — the inverse of relone_add_user_to_group. Single user, single group per call. The user will lose every permission they were receiving via this group; if their access to a workspace came only through this group, they will lose that workspace too. Eventually consistent: the upstream Group Manager call returns immediately, but the removal propagates through ADS agents and service bus over several minutes. A subsequent relone_list_user_groups call may briefly still show the membership. Server-side idempotent: removing a user that isn't currently a member is a no-op. Uses the Group Manager Kepler service (Relativity-Identity v1).

relone_remove_user_from_group

Poll a usage report until it reaches "Completed" status or times out. Returns the final report object on success. Use after relone_usage_generate_report. IMPORTANT: This tool blocks while polling for up to maxWaitMs (default 2 minutes, maximum 10 minutes). PERMISSION NOTE: Returns 403 unless the OAuth client's Context User is in a group with 'View Instance-wide Usage Reports' (or 'View Client Domain Usage Reports') under Admin Operations, plus 'Management Console' + 'Usage Reports' under Tab Visibility. System Admin alone is not sufficient — this permission must be explicitly granted.

relone_usage_wait_for_report

Wait for an asynchronous workspace-create job to reach a terminal state (COMPLETED or ERROR). Polls internally and emits MCP progress notifications — rendered inline by clients that support them, ignored gracefully otherwise. The upstream creation job runs independently of this wait: cancelling the tool call (for example, the user interrupting to ask something else) does NOT cancel the workspace creation; call this tool again with the same JobId to resume watching. If the wait timeout elapses without reaching a terminal state, returns the current non-terminal status — call again to keep waiting. On COMPLETED, call relone_get_workspace with the returned WorkspaceId for full details.

relone_wait_for_workspace_create_job