Tools reference - Artu Compliance SDK

Tools are discovered through standard MCP tools/list. Each tool’s filter / sort parameters are built from the connection scope’s registry schema and trimmed for agent use, so a scoped connection advertises flat scope-specific filters (e.g. rfc, curp) while an unscoped connection sees only base fields.

Read tools

Tool	Description
`whoami`	Return the connected organization, environment, scope, and read permissions so you can orient before making calls.
`list_clients`	List clients with optional filtering, sorting, and pagination. Returns a summary of each client. Paginates with `offset`/`limit`; the response includes `total`, `offset`, `limit`, and `hasMore`.
`get_client`	Retrieve a client by ID or externalId. Optionally fan out sub-resources via the include parameter. Included documents are metadata only — to download a file, call get_document with its id to obtain a time-limited downloadUrl.
`get_client_checklist`	Get the compliance checklist for a client. On an unscoped connection, pass the `scope` to evaluate the checklist for.
`list_transactions`	List transactions with optional filtering, sorting, and pagination. Returns a summary of each transaction. Paginates with `offset`/`limit`; the response includes `total`, `offset`, `limit`, and `hasMore`.
`get_transaction`	Retrieve a transaction by ID. Optionally embed related evidence via the include parameter. Embedded evidence is metadata only — to download a file, call get_evidence with its id to obtain a time-limited downloadUrl.
`list_alerts`	List alerts with optional filtering, sorting, and pagination. Returns a summary of each alert. Paginates with `offset`/`limit`; the response includes `total`, `offset`, `limit`, and `hasMore`.
`get_alert`	Retrieve a full alert by ID, with its alert items fanned out under `alertItems`.
`list_workflows`	List workflows with optional filtering and pagination. Returns a summary of each workflow. Paginates with `offset`/`limit`; the response includes `total`, `offset`, `limit`, and `hasMore`. Note: sorting is not supported by the workflows API.
`get_workflow`	Retrieve a workflow by ID.
`list_workflow_executions`	List workflow executions with optional filtering and pagination. Returns a summary of each execution. Paginates with `offset`/`limit`; the response includes `total`, `offset`, `limit`, and `hasMore`. Note: sorting is not supported by the executions API.
`get_workflow_execution`	Retrieve a workflow execution by ID. The execution trace is summarized — per-node type, duration, row counts, and errors are kept, but the raw SQL and internal column layout are omitted.
`wait_for_workflow_execution`	Block up to `timeoutMs` (default 30s, max 50s) until a workflow execution reaches a terminal state or pauses for human input, then return its tracking summary. The summary’s `producedRecords` lists everything the run created/updated (alerts, clients, transactions, subresources; capped at 50 per type); `alertIds` is the alert subset of `producedRecords`; `producedFiles` describes any files the run produced (filename, contentType, size). Use after run_workflow returns `queued` instead of polling get_workflow_execution.
`list_reports`	List reports with optional filtering, sorting, and pagination. Returns a summary of each report. Paginates with `offset`/`limit`; the response includes `total`, `offset`, `limit`, and `hasMore`.
`get_report`	Retrieve a report by ID, including its metadata and a time-limited download URL for the filed report file.
`get_document`	Resolve a document id to its metadata and a time-limited download URL.
`get_evidence`	Resolve an evidence id to its metadata, a time-limited download URL, and the transactions it is linked to.

Action tools

All action tools advertise readOnlyHint: false and exist only on scoped connections.

Tool	Description	Destructive	Idempotent
`save_client`	Create or update a client, optionally with nested addresses, contactMethods, and bankAccounts (synced atomically). Pass `id` to update an existing client (send only the fields to change in `data`); pass `externalId` (without `id`) to idempotently create-or-update by your stable identifier — safe to retry; pass neither to create. Nested array items without `id` are created; items with `id` are updated; deleting is not supported here. The schema advertises every field as optional because this tool also handles partial updates; on create the server enforces the required fields and returns precise per-field errors. IMPORTANT — externalId semantics differ by path: (a) without nested arrays, `externalId` triggers a full create-or-update (upsertByExternalId) that may create the client, so `data` must contain the complete set of required create fields; (b) with nested arrays, the tool first looks up the existing client by `externalId` and performs a partial update — in this case `data` is optional and only contains the fields to change.	—	—
`save_transaction`	Create or update a transaction. Pass `id` to update an existing transaction (send only the fields to change in `data`); pass `externalId` (without `id`) to idempotently create-or-update by your stable identifier — safe to retry; pass neither to create. IMPORTANT — when using `externalId` (without `id`), the operation is a full create-or-update (upsertByExternalId) that may create the transaction, so `data` must contain the complete set of required create fields. The schema advertises every field as optional because this tool also handles partial updates; on create the server enforces the required fields and returns precise per-field errors.	—	—
`update_alert_status`	Transition an alert to a new lifecycle status (e.g. take it into review, resolve, or dismiss it). Calling with the alert’s current status is a safe no-op. System-managed report-validation states cannot be set directly; invalid transitions are rejected by the server.	—	✓
`run_workflow`	Run a workflow. By default waits up to 30s for it to finish and returns the executionId and a status: `completed` (done — check `error` for soft failures and `producedRecords` for everything the run created/updated: alerts, clients, transactions, subresources, capped at 50 per type; `alertIds` is the alert subset of `producedRecords`; `producedFiles` describes any files the run produced: filename, contentType, size), `waiting_for_input` (paused on a human-in-the-loop step; a person must act on the execution), or `queued` (still running — follow up with wait_for_workflow_execution or get_workflow_execution). Pass `wait: false` to return immediately after the run is queued (status `queued`) without waiting. Use triggerType `manual` (default; optional `inputs`) or `event` (requires `entityType` + `entityId`).	—	—
`cancel_workflow_execution`	Cancel a running workflow execution. The run stops and is marked cancelled; the workflow itself is unchanged and can be run again. Safe to call on an already-finished execution — the terminal status wins and the response carries `alreadyFinished: true`.	✓	✓
`add_client_document`	Create a document record attached to a client. When `contentType` is provided, the response includes a presigned `upload` URL — HTTP PUT the file bytes to it (with a matching Content-Type header), then call `confirm_document_upload`. Without `contentType`, the record is metadata-only and needs no confirmation.	—	—
`confirm_document_upload`	Confirm that a document file was uploaded to the presigned URL returned by add_client_document. Transitions the document from pending_upload to uploaded.	—	✓
`add_transaction_evidence`	Attach evidence to a transaction. Pass `data` to create a new evidence record (linked to the transaction immediately after creation): include `contentType` to get a presigned `upload` URL — HTTP PUT the file bytes to it, then call `confirm_evidence_upload`; omit `contentType` for data-only evidence. Or pass `evidenceId` to link an existing evidence record instead (also the retry path if a previous call reported a link failure).	—	—
`confirm_evidence_upload`	Confirm that an evidence file was uploaded to the presigned URL returned by add_transaction_evidence. Transitions the evidence from pending_upload to uploaded.	—	✓

Annotations

Every tool advertises explicit MCP annotations:

readOnlyHint — true for read tools; false for action tools.
destructiveHint — true only where a call removes or supersedes state (e.g. cancelling a running workflow execution).
idempotentHint — true where repeating the call with the same input is safe (e.g. confirming an upload, or save_* with an id / externalId).

MCP clients should require user confirmation before mutating calls, and many do so by default.

Pagination

list_* tools use offset-based pagination. Inputs: offset (default 0) and limit (default 20, max 200). Each response carries:

{ "items": ["…summaries"], "total": 0, "limit": 20, "offset": 0, "hasMore": false }

total is the full matching count; advance by increasing offset (e.g. offset + limit) while hasMore is true. Full objects come from the get_* tools.

Workflow run results

run_workflow and wait_for_workflow_execution return the records and files a run produced:

producedRecords — the compliance records created or updated by the run (e.g. alerts, transactions), with their ids and types.
producedFiles — files the run generated (e.g. reports), each resolvable to a time-limited download URL via the matching get_* tool.

​Read tools

​Action tools

​Annotations

​Pagination

​Workflow run results

Read tools

Action tools

Annotations

Pagination

Workflow run results