> ## Documentation Index > Fetch the complete documentation index at: https://docs.artu.ai/llms.txt > Use this file to discover all available pages before exploring further. # Tools reference > The Artu MCP read tools and action tools, with their MCP annotations, pagination, and response shapes 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: ```json theme={null} { "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.