Appearance
Tools
The server exposes the tools below. Tools that declare required access only appear in tools/list when your account holds every listed permission, so the assistant sees exactly the set you are allowed to use.
Available tools
| Tool | Access required | Description |
|---|---|---|
ping | (none) | Health-check tool that returns pong (and echoes any provided message). |
suralink_health | (none) | Calls the Suralink API's /health endpoint and returns its status. Requires an authenticated session. |
get_engagements | engagement:read | Lists Suralink engagements (a.k.a. request lists) for the authenticated user's currently-active client. Takes no arguments — the active client is selected server-side by the session. Returns { active, inactive, archived } where each bucket is an array of { id, customId, name }. |
get_request_items_for_engagement | engagement:read | Lists request items on a specific engagement. Required arguments: engagementId (integer) and organizationId (UUID, owning organization). Optional: limit (defaults to 25) and offset for paging. |
get_user_metadata | (none) | Returns the authenticated user's role and userType. No inputs. |
list_firms | firm:read | Lists the firms the authenticated user can access. No inputs. |
get_firm | firm:read | Returns licenses and features for a single firm. firmId is the firm's numeric id (from list_firms) — not the organizationId UUID. |
list_departments | firm:read | Lists departments for a firm. Required: organizationId. |
get_department | firm:read | Returns info for a single department. Required: organizationId, departmentId. |
get_organization_user | firmusers:read | Returns a user's role and departmentId. userId is the user's UUID (uuid field from list_organization_users) — not the numeric userId/id. |
list_organization_users | firmusers:read | Paged, sortable, filterable, searchable list of an organization's users. Required: organizationId. Optional: limit (default 25), offset, search, sort, filter. |
export_organization_users | firmusers:read | Bulk tabular export of an organization's firm users. Body returned as raw text. Required: organizationId. |
list_client_org_users | firmusers:read | Lists firm users assigned to a client. Required: organizationId, clientId. |
list_assignable_users_for_request_item | firmusers:read | Lists firm and client users assignable to a request item. Required: requestItemId. |
list_clients | clients:read | Lists clients for an organization. Required: organizationId. |
list_my_clients | (none) | Lists every Suralink client the authenticated user belongs to as a client user. No inputs. Distinct from list_clients (firm-user view). |
list_request_lists_for_client | engagement:read | Lists request lists for a client filtered by state. Required: organizationId, clientId, state. |
get_request_list_summary | engagement:read | Returns a summary of a request list. Required: organizationId, requestListId. |
get_request_list_state | engagement:read | Returns the state of a request list. Required: organizationId, requestListId. |
get_request_item | engagement:read | Returns info (including state) for a request item. Required: organizationId, requestListId, requestItemId. |
get_request_item_annotations_bulk | engagement:read | Fetches annotations by IDs for a request item. Each annotationIds entry must be a 26-character ULID (Crockford base32). Required: organizationId, requestListId, requestItemId, annotationIds. |
get_request_item_files_summary | engagement:read | Lists files attached to a request item. Required: organizationId, requestListId, requestItemId. |
list_my_engagements | engagement:read | Lists every engagement and report the authenticated user can access as a client user. No inputs. Collapses the list_my_clients to per-client list_request_lists_for_client fanout into one call. Firm users will see []. |
list_request_item_comments | engagement:read | Lists comment history (annotations with their comment threads) for a request item, with pagination. Required: organizationId, requestListId, requestItemId. Optional: limit, offset, commentId. |
list_request_item_comments_bulk | engagement:read | Fetches comments for an array of annotation/document item IDs in one call. Required: organizationId, requestListId, requestItemId, itemIds[] (min 1). Optional: annotationType (1 = requestItem, 2 = document), system. |
get_request_item_detail | engagement:read | Returns drill-down detail (state, dueDate, priority, category/subcategory names, engagement name) for a single request item. Required: engagementId, requestId. Distinct from get_request_item, which addresses the same item by org / request-list path. |
get_request_item_history | engagement:read | Returns paginated event history (uploads, state changes, comments) for a request item. Required: requestItemId, organizationId (UUID), requestListId. Optional: limit, offset. |
list_my_recent_clients | clients:read | Returns the authenticated user's most recently viewed clients within an organization. Required: organizationId. |
list_engagement_firm_users | firmusers:read | Returns firm users with access to an engagement. Required: engagementId. Distinct from list_client_org_users (firm users on a client, not an engagement). |
Access model
Each tool may declare required access. The server hides a tool from tools/list unless every requirement is present for your account. The access names group broadly as:
| Access | Covers |
|---|---|
firm:read | Firm and department lookups. |
firmusers:read | Firm-user and assignable-user lookups. |
clients:read | Client lists and recent-client lookups. |
engagement:read | Engagements, request lists, request items, files, comments, and history. |
Beyond per-tool access, your selected organization must have Suralink MCP access enabled. See Getting Started for details.