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. When reporting totals to the user, cite TotalCount — not the length of Items.

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. On ERROR, creation failed; direct the user to the RelativityOne UI for detailed error info. 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. When reporting totals to the user, cite TotalCount — not the length of Items. Use the field name from relone_get_fields results as the fieldName parameter.

relone_list_choices

List legal clients configured in the RelativityOne 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. When reporting totals to the user, cite TotalCount — not the length of Items. 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. When reporting totals, cite TotalCount, not Items.Length. 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 RelativityOne 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. When reporting totals to the user, cite TotalCount — not the length of Items. 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. When reporting totals to the user, cite TotalCount — not the length of Items.

relone_list_object_types

List security groups on the RelativityOne 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. When reporting totals to the user, cite TotalCount — not the length of Items. 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 RelativityOne 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. When reporting totals to the user, cite TotalCount — not the length of Items. 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. When reporting totals, cite TotalCount, not Items.Length. 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. When reporting totals to the user, cite TotalCount — not the length of Items. When checking whether a specific known group has access, pass nameFilter or a condition like 'ArtifactID' == <id> rather than paging through all groups — workspaces with hundreds of groups otherwise require multiple paged calls.

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. When reporting totals to the user, cite TotalCount — not the length of Items. Note: template-based workspace creation can take 5+ minutes for DB restore and permissions setup.

relone_list_workspace_templates

List workspaces on the connected RelativityOne instance with optional name filtering. Returns a paginated envelope with TotalCount (authoritative total), an Items page, ActiveFilters, and ProjectionUsed. When reporting totals to the user, cite TotalCount — not the length of Items.

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. Use this in clients that cannot autonomously poll between turns (e.g. standard chat UIs); in clients that can poll autonomously, prefer relone_get_workspace_create_job instead. 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