> For the complete documentation index, see [llms.txt](https://k-ai.gitbook.io/knowledge-ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://k-ai.gitbook.io/knowledge-ai/k-ai-mcp/audit-tools.md).

# Audit tools

Server: `https://api-audit.kai-studio.ai/mcp`. Twenty-one curated tools — a subset of the 48 REST endpoints of the K-AI Audit API. The selection is conflict-first: start at the dashboard, iterate on open conflicts, confirm modifications, close (or ignore). Admin operations (instance create/delete, user membership, daily/per-user stats, duplicates, owner assignment) remain REST-only. See [Schema stability policy](/knowledge-ai/k-ai-mcp/schema-stability.md) for our compatibility commitments.

Every response is wrapped as `{"response": <payload>}`. Identifiers are prefixed and must be passed back as-is: `ki_` (K-AI instance), `qc_` (question conflict), `fc_` (full-audit conflict), `mq_` (mandatory question), `ms_` (missing subject), `kd_` (K-AI document).

## Priority

Two conflict surfaces exist, and they are not equal. Resolve **priority conflicts first**:

* Every **question conflict** (`audit_question_conflict_list`) is priority by definition — a user explicitly asked about the affected documents.
* Every **full-audit conflict linked to a mandatory question** — list with `only_linked_to_question=true`; these come back flagged `is_important` and share priority with question conflicts.

Unlinked full-audit conflicts are the secondary worklist — the broad per-instance review. Surface them only after the priority conflicts are exhausted, or when the expert explicitly asks for the broad audit.

## Tools by workflow

| Workflow group                      | Tools                                                                                                                                                                                          |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Workflow entry                      | `audit_dashboard_get`                                                                                                                                                                          |
| Conflict-first flow (primary)       | `audit_question_conflict_list` · `audit_question_conflict_get` · `audit_question_conflict_set_answer` · `audit_question_conflict_close` · `audit_question_conflict_ignore`                     |
| Document helpers                    | `audit_documents_get_by_ids` · `audit_documents_get_recommendations`                                                                                                                           |
| Mandatory questions (admin surface) | `audit_mandatory_question_list` · `audit_mandatory_question_create` · `audit_mandatory_question_force_analyze`                                                                                 |
| Missing subjects                    | `audit_missing_subject_list` · `audit_missing_subject_find` · `audit_missing_subject_list_questions` · `audit_missing_subject_set_state` · `audit_missing_subject_generate_compagnon_document` |
| Full-audit broad review             | `audit_full_audit_conflict_list` · `audit_full_audit_conflict_get` · `audit_full_audit_conflict_set_answer` · `audit_full_audit_conflict_ignore` · `audit_full_audit_conflict_close`           |

## Workflow entry

### audit\_dashboard\_get

Returns a summary of every audit instance the authenticated user can access, with per-instance counts of unresolved conflicts (questions + full-audit), pending mandatory questions, and pending missing subjects. The recommended entrypoint before drilling into a specific instance — every other audit operation needs a `ki_*` instance\_id taken from this dashboard.

**Input schema**

| Field    | Type | Required | Description        |
| -------- | ---- | -------- | ------------------ |
| *(none)* | —    | —        | Empty object `{}`. |

**Output schema**

| Field                                                  | Type            | Description                        |
| ------------------------------------------------------ | --------------- | ---------------------------------- |
| `response.instances`                                   | array           | Per-instance dashboard rows.       |
| `response.instances[].id`                              | string (`ki_*`) | K-AI instance identifier.          |
| `response.instances[].name`                            | string          | Display name.                      |
| `response.instances[].unresolved_conflicts`            | integer         | Open question-driven conflicts.    |
| `response.instances[].unresolved_full_audit_conflicts` | integer         | Open full-audit conflicts.         |
| `response.instances[].pending_mandatory_questions`     | integer         | Questions not yet resolved.        |
| `response.instances[].pending_missing_subjects`        | integer         | Missing subjects not yet resolved. |

{% tabs %}
{% tab title="Python (MCP SDK)" %}

```python
result = await session.call_tool("audit_dashboard_get", {})
print(result.structuredContent)
```

{% endtab %}

{% tab title="TypeScript (MCP SDK)" %}

```ts
const result = await client.callTool({
  name: "audit_dashboard_get",
  arguments: {},
});
console.log(result.structuredContent);
```

{% endtab %}

{% tab title="Raw HTTP" %}

```bash
curl -X POST https://api-audit.kai-studio.ai/audit/dashboard/get-my-dashboard \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" -d '{}'
```

{% endtab %}
{% endtabs %}

## Conflict-first flow (primary)

The canonical resolution path. Conflicts are surfaced from the dashboard, listed, inspected, answered, and closed. `audit_question_conflict_set_answer` returns inline AI recommendations the expert must apply (and confirm) before calling `audit_question_conflict_close`.

```mermaid
flowchart LR
    A[audit_dashboard_get] --> B[audit_question_conflict_list]
    B --> C[audit_question_conflict_get]
    C --> D[audit_question_conflict_set_answer]
    D -->|expert confirms modifications applied| E[audit_question_conflict_close]
    C -->|false positive, no change needed| F[audit_question_conflict_ignore]
```

### audit\_question\_conflict\_list

Paginated flat list of question-driven conflicts. Default `state_in=['OPEN']` — the primary expert worklist. Allowed states: `OPEN`, `ANSWERED`, `RECOMMENDATIONS_READY`, `MANAGED`, `IGNORED`. Filter by `question_id_in` (`mq_*`) or `document_id_in` (`kd_*`) to scope to a question or a document.

**Input schema**

| Field            | Type                             | Required        | Description                                                                                                                                      |
| ---------------- | -------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `instance_id`    | string (`ki_*`)                  | yes             | K-AI instance identifier.                                                                                                                        |
| `offset`         | integer (0–100000)               | no (default 0)  | Number of conflicts to skip.                                                                                                                     |
| `limit`          | integer (1–1000)                 | no (default 25) | Maximum conflicts to return.                                                                                                                     |
| `state_in`       | array of state \| null           | no              | Defaults to `['OPEN']`. One or more of `OPEN`, `ANSWERED`, `RECOMMENDATIONS_READY`, `MANAGED`, `IGNORED`. Empty array disables the state filter. |
| `question_id_in` | array of string (`mq_*`) \| null | no              | Restrict to conflicts triggered by these questions.                                                                                              |
| `document_id_in` | array of string (`kd_*`) \| null | no              | Restrict to conflicts touching these documents.                                                                                                  |

**Output schema**

| Field                                  | Type            | Description                                                                            |
| -------------------------------------- | --------------- | -------------------------------------------------------------------------------------- |
| `response`                             | array           | Conflicts, hydrated with `document_name` and `document_url`.                           |
| `response[].id`                        | string (`qc_*`) | Question-conflict identifier.                                                          |
| `response[].instance_id`               | string (`ki_*`) | Owning instance.                                                                       |
| `response[].question_id`               | string (`mq_*`) | Triggering mandatory question.                                                         |
| `response[].state`                     | enum            | `OPEN` \| `ANSWERED` \| `RECOMMENDATIONS_READY` \| `MANAGED` \| `IGNORED`.             |
| `response[].extraproperties.documents` | array           | Contradicting excerpts with `document_id`, `document_name`, `document_url`, `excerpt`. |

{% tabs %}
{% tab title="Python (MCP SDK)" %}

```python
result = await session.call_tool(
    "audit_question_conflict_list",
    {"instance_id": "ki_abc123", "offset": 0, "limit": 25},
)
```

{% endtab %}

{% tab title="TypeScript (MCP SDK)" %}

```ts
const result = await client.callTool({
  name: "audit_question_conflict_list",
  arguments: { instance_id: "ki_abc123", offset: 0, limit: 25 },
});
```

{% endtab %}

{% tab title="Raw HTTP" %}

```bash
curl -X POST https://api-audit.kai-studio.ai/audit/conflict/list-conflicts-for-instance \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"instance_id": "ki_abc123", "offset": 0, "limit": 25}'
```

{% endtab %}
{% endtabs %}

### audit\_question\_conflict\_get

Returns the full detail of a conflict — contradicting excerpts, triggering question, companion questions, state, and any saved expert answer. Required before calling `audit_question_conflict_set_answer` unless the list response already provides the full context.

**Input schema**

| Field         | Type            | Required | Description                   |
| ------------- | --------------- | -------- | ----------------------------- |
| `instance_id` | string (`ki_*`) | yes      | K-AI instance identifier.     |
| `conflict_id` | string (`qc_*`) | yes      | Question-conflict identifier. |

**Output schema**

| Field                                | Type            | Description                                                                |
| ------------------------------------ | --------------- | -------------------------------------------------------------------------- |
| `response`                           | object \| null  | Conflict detail, or null if not found.                                     |
| `response.id`                        | string (`qc_*`) | Conflict identifier.                                                       |
| `response.state`                     | enum            | `OPEN` \| `ANSWERED` \| `RECOMMENDATIONS_READY` \| `MANAGED` \| `IGNORED`. |
| `response.question_id`               | string (`mq_*`) | Triggering question.                                                       |
| `response.extraproperties.documents` | array           | Contradicting excerpts.                                                    |

{% tabs %}
{% tab title="Python (MCP SDK)" %}

```python
result = await session.call_tool(
    "audit_question_conflict_get",
    {"instance_id": "ki_abc123", "conflict_id": "qc_xyz789"},
)
```

{% endtab %}

{% tab title="TypeScript (MCP SDK)" %}

```ts
const result = await client.callTool({
  name: "audit_question_conflict_get",
  arguments: { instance_id: "ki_abc123", conflict_id: "qc_xyz789" },
});
```

{% endtab %}

{% tab title="Raw HTTP" %}

```bash
curl -X POST https://api-audit.kai-studio.ai/audit/conflict/get \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"instance_id": "ki_abc123", "conflict_id": "qc_xyz789"}'
```

{% endtab %}
{% endtabs %}

### audit\_question\_conflict\_set\_answer

Records the expert resolution and immediately returns per-document modification recommendations inline. Sync LLM call (\~5s typical, \~10s p99). After receiving the response, render `recommendations` as a markdown table (`Document | Action`) and ask the expert whether each modification was applied before calling `audit_question_conflict_close`. The conflict stays in `RECOMMENDATIONS_READY` until `_close` is called. If `recommendations` is empty, the LLM crew failed for this conflict — re-call `set_answer` to retry (do NOT call `audit_documents_get_recommendations`, it only reads persisted recommendations).

**Input schema**

| Field         | Type            | Required | Description                   |
| ------------- | --------------- | -------- | ----------------------------- |
| `instance_id` | string (`ki_*`) | yes      | K-AI instance identifier.     |
| `conflict_id` | string (`qc_*`) | yes      | Question-conflict identifier. |
| `answer`      | string          | yes      | Expert resolution text.       |

**Output schema**

| Field                                      | Type            | Description                                                     |
| ------------------------------------------ | --------------- | --------------------------------------------------------------- |
| `response.conflict`                        | object          | The updated conflict (state typically `RECOMMENDATIONS_READY`). |
| `response.recommendations`                 | array           | Per-document modification recommendations.                      |
| `response.recommendations[].conflict_id`   | string          | Source conflict.                                                |
| `response.recommendations[].document_id`   | string (`kd_*`) | Target document.                                                |
| `response.recommendations[].document_name` | string \| null  | Document name.                                                  |
| `response.recommendations[].document_url`  | string \| null  | Document URL for citation.                                      |
| `response.recommendations[].type`          | string          | Recommendation type.                                            |
| `response.recommendations[].action`        | string          | Recommended action text.                                        |

{% tabs %}
{% tab title="Python (MCP SDK)" %}

```python
result = await session.call_tool(
    "audit_question_conflict_set_answer",
    {"instance_id": "ki_abc123", "conflict_id": "qc_xyz789",
     "answer": "The 30-day refund window is the canonical policy."},
)
```

{% endtab %}

{% tab title="TypeScript (MCP SDK)" %}

```ts
const result = await client.callTool({
  name: "audit_question_conflict_set_answer",
  arguments: {
    instance_id: "ki_abc123",
    conflict_id: "qc_xyz789",
    answer: "The 30-day refund window is the canonical policy.",
  },
});
```

{% endtab %}

{% tab title="Raw HTTP" %}

```bash
curl -X POST https://api-audit.kai-studio.ai/audit/conflict/set-answer \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"instance_id":"ki_abc123","conflict_id":"qc_xyz789","answer":"The 30-day refund window is the canonical policy."}'
```

{% endtab %}
{% endtabs %}

### audit\_question\_conflict\_close

Transitions a conflict to `MANAGED`. Requires the conflict to be in `RECOMMENDATIONS_READY` (or `ANSWERED`, if the expert decides to close without recommendations). Idempotent if already `MANAGED`. Call only after the expert confirmed every modification was applied (or accepts a partial application).

**Input schema**

| Field         | Type            | Required | Description                   |
| ------------- | --------------- | -------- | ----------------------------- |
| `instance_id` | string (`ki_*`) | yes      | K-AI instance identifier.     |
| `conflict_id` | string (`qc_*`) | yes      | Question-conflict identifier. |

**Output schema**

| Field      | Type           | Description                                |
| ---------- | -------------- | ------------------------------------------ |
| `response` | object \| null | The conflict in its new state (`MANAGED`). |

{% tabs %}
{% tab title="Python (MCP SDK)" %}

```python
result = await session.call_tool(
    "audit_question_conflict_close",
    {"instance_id": "ki_abc123", "conflict_id": "qc_xyz789"},
)
```

{% endtab %}

{% tab title="TypeScript (MCP SDK)" %}

```ts
const result = await client.callTool({
  name: "audit_question_conflict_close",
  arguments: { instance_id: "ki_abc123", conflict_id: "qc_xyz789" },
});
```

{% endtab %}

{% tab title="Raw HTTP" %}

```bash
curl -X POST https://api-audit.kai-studio.ai/audit/conflict/set-managed \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"instance_id": "ki_abc123", "conflict_id": "qc_xyz789"}'
```

{% endtab %}
{% endtabs %}

### audit\_question\_conflict\_ignore

Marks a question conflict as `IGNORED` — the expert judged it a non-issue or a false positive that needs no change. Terminal: the conflict leaves the active worklist. Use this instead of `_close` when no document modification is warranted. Idempotent if already `IGNORED`. This is the `qc_` counterpart of `audit_full_audit_conflict_ignore`.

**Input schema**

| Field         | Type            | Required | Description                   |
| ------------- | --------------- | -------- | ----------------------------- |
| `instance_id` | string (`ki_*`) | yes      | K-AI instance identifier.     |
| `conflict_id` | string (`qc_*`) | yes      | Question-conflict identifier. |

**Output schema**

| Field      | Type           | Description                                |
| ---------- | -------------- | ------------------------------------------ |
| `response` | object \| null | The conflict in its new state (`IGNORED`). |

{% tabs %}
{% tab title="Python (MCP SDK)" %}

```python
result = await session.call_tool(
    "audit_question_conflict_ignore",
    {"instance_id": "ki_abc123", "conflict_id": "qc_xyz789"},
)
```

{% endtab %}

{% tab title="TypeScript (MCP SDK)" %}

```ts
const result = await client.callTool({
  name: "audit_question_conflict_ignore",
  arguments: { instance_id: "ki_abc123", conflict_id: "qc_xyz789" },
});
```

{% endtab %}

{% tab title="Raw HTTP" %}

```bash
curl -X POST https://api-audit.kai-studio.ai/audit/conflict/set-ignored \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"instance_id": "ki_abc123", "conflict_id": "qc_xyz789"}'
```

{% endtab %}
{% endtabs %}

## Document helpers

Lookup tools used to enrich conflict displays and re-surface past recommendations.

### audit\_documents\_get\_by\_ids

Resolves document name, URL, and extra properties for up to 100 `kd_*` ids in one call. Side effect: caches the resolved `web_url` on `audit.documents` so subsequent conflict reads surface the URL directly from the database.

**Input schema**

| Field          | Type                                  | Required | Description               |
| -------------- | ------------------------------------- | -------- | ------------------------- |
| `instance_id`  | string (`ki_*`)                       | yes      | K-AI instance identifier. |
| `document_ids` | array of string (`kd_*`), 1–100 items | yes      | Document IDs to resolve.  |

**Output schema**

| Field                        | Type                    | Description                |
| ---------------------------- | ----------------------- | -------------------------- |
| `response`                   | array                   | Resolved document records. |
| `response[].id`              | string (`kd_*`) \| null | Document identifier.       |
| `response[].name`            | string \| null          | Document name.             |
| `response[].url`             | string \| null          | Web URL of the document.   |
| `response[].extraproperties` | object                  | Additional metadata.       |

{% tabs %}
{% tab title="Python (MCP SDK)" %}

```python
result = await session.call_tool(
    "audit_documents_get_by_ids",
    {"instance_id": "ki_abc123",
     "document_ids": ["kd_def456", "kd_ghi789"]},
)
```

{% endtab %}

{% tab title="TypeScript (MCP SDK)" %}

```ts
const result = await client.callTool({
  name: "audit_documents_get_by_ids",
  arguments: {
    instance_id: "ki_abc123",
    document_ids: ["kd_def456", "kd_ghi789"],
  },
});
```

{% endtab %}

{% tab title="Raw HTTP" %}

```bash
curl -X POST https://api-audit.kai-studio.ai/audit/document/get-by-ids \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"instance_id":"ki_abc123","document_ids":["kd_def456","kd_ghi789"]}'
```

{% endtab %}
{% endtabs %}

### audit\_documents\_get\_recommendations

Returns every AI-generated modification recommendation accumulated on a document across all resolved conflicts of the current instance. Use when the expert returns to a document later or asks what to change without naming a specific conflict — **not** as a retry for a freshly-failed `audit_question_conflict_set_answer` (this endpoint only reads persisted recommendations).

**Input schema**

| Field         | Type            | Required | Description               |
| ------------- | --------------- | -------- | ------------------------- |
| `instance_id` | string (`ki_*`) | yes      | K-AI instance identifier. |
| `document_id` | string (`kd_*`) | yes      | Target document.          |

**Output schema**

| Field                                    | Type            | Description                       |
| ---------------------------------------- | --------------- | --------------------------------- |
| `response.document_id`                   | string (`kd_*`) | Document identifier.              |
| `response.name`                          | string          | Document name.                    |
| `response.recommendations`               | array           | Persisted recommendation entries. |
| `response.recommendations[].conflict_id` | string (`qc_*`) | Originating conflict.             |
| `response.recommendations[].document_id` | string (`kd_*`) | Target document.                  |
| `response.recommendations[].type`        | string          | Recommendation type.              |
| `response.recommendations[].action`      | string          | Recommended action text.          |

{% tabs %}
{% tab title="Python (MCP SDK)" %}

```python
result = await session.call_tool(
    "audit_documents_get_recommendations",
    {"instance_id": "ki_abc123", "document_id": "kd_def456"},
)
```

{% endtab %}

{% tab title="TypeScript (MCP SDK)" %}

```ts
const result = await client.callTool({
  name: "audit_documents_get_recommendations",
  arguments: { instance_id: "ki_abc123", document_id: "kd_def456" },
});
```

{% endtab %}

{% tab title="Raw HTTP" %}

```bash
curl -X POST https://api-audit.kai-studio.ai/audit/document/get-recommendations \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"instance_id": "ki_abc123", "document_id": "kd_def456"}'
```

{% endtab %}
{% endtabs %}

## Mandatory questions (admin surface)

Auxiliary worklist — the primary expert worklist is the conflict-first flow. Use these tools to inspect or manage mandatory questions directly, or to recover a `REFUSED` question by forcing re-analysis.

### audit\_mandatory\_question\_list

Lists mandatory questions for an instance. Use to inspect or manage questions directly, or to find a `REFUSED` question to pass to `audit_mandatory_question_force_analyze`.

**Input schema**

| Field         | Type               | Required | Description                               |
| ------------- | ------------------ | -------- | ----------------------------------------- |
| `instance_id` | string (`ki_*`)    | yes      | K-AI instance identifier.                 |
| `offset`      | integer (0–100000) | yes      | Number of items to skip.                  |
| `limit`       | integer (1–1000)   | yes      | Maximum items to return.                  |
| `state`       | string \| null     | no       | Optional mandatory-question state filter. |

**Output schema**

| Field                         | Type                     | Description                                   |
| ----------------------------- | ------------------------ | --------------------------------------------- |
| `response`                    | array                    | Mandatory questions.                          |
| `response[].id`               | string (`mq_*`)          | Question identifier.                          |
| `response[].question`         | string                   | Question text.                                |
| `response[].state`            | string                   | Current state.                                |
| `response[].instance_id`      | string (`ki_*`)          | Owning instance.                              |
| `response[].linked_conflicts` | array of string (`fc_*`) | Full-audit conflicts linked to this question. |

{% tabs %}
{% tab title="Python (MCP SDK)" %}

```python
result = await session.call_tool(
    "audit_mandatory_question_list",
    {"instance_id": "ki_abc123", "offset": 0, "limit": 50},
)
```

{% endtab %}

{% tab title="TypeScript (MCP SDK)" %}

```ts
const result = await client.callTool({
  name: "audit_mandatory_question_list",
  arguments: { instance_id: "ki_abc123", offset: 0, limit: 50 },
});
```

{% endtab %}

{% tab title="Raw HTTP" %}

```bash
curl -X POST https://api-audit.kai-studio.ai/audit/mandatory-question/list \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"instance_id": "ki_abc123", "offset": 0, "limit": 50}'
```

{% endtab %}
{% endtabs %}

### audit\_mandatory\_question\_create

Creates a mandatory question for an instance. The audit worker will analyse the question and surface any resulting conflicts on the conflict worklist.

**Input schema**

| Field         | Type            | Required | Description               |
| ------------- | --------------- | -------- | ------------------------- |
| `instance_id` | string (`ki_*`) | yes      | K-AI instance identifier. |
| `question`    | string          | yes      | Question text.            |

**Output schema**

| Field      | Type    | Description                           |
| ---------- | ------- | ------------------------------------- |
| `response` | boolean | True when the question was persisted. |

{% tabs %}
{% tab title="Python (MCP SDK)" %}

```python
result = await session.call_tool(
    "audit_mandatory_question_create",
    {"instance_id": "ki_abc123",
     "question": "What is the refund window for damaged goods?"},
)
```

{% endtab %}

{% tab title="TypeScript (MCP SDK)" %}

```ts
const result = await client.callTool({
  name: "audit_mandatory_question_create",
  arguments: {
    instance_id: "ki_abc123",
    question: "What is the refund window for damaged goods?",
  },
});
```

{% endtab %}

{% tab title="Raw HTTP" %}

```bash
curl -X POST https://api-audit.kai-studio.ai/audit/mandatory-question/create \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"instance_id":"ki_abc123","question":"What is the refund window for damaged goods?"}'
```

{% endtab %}
{% endtabs %}

### audit\_mandatory\_question\_force\_analyze

Forces re-analysis of a refused mandatory question. Only valid when the question is in `REFUSED` state. Recomputes its embedding and re-enqueues a `CheckQuestionTask` for the audit worker.

**Input schema**

| Field         | Type            | Required | Description                    |
| ------------- | --------------- | -------- | ------------------------------ |
| `instance_id` | string (`ki_*`) | yes      | K-AI instance identifier.      |
| `question_id` | string (`mq_*`) | yes      | Mandatory question identifier. |

**Output schema**

| Field      | Type    | Description                       |
| ---------- | ------- | --------------------------------- |
| `response` | boolean | True when re-analysis was queued. |

{% tabs %}
{% tab title="Python (MCP SDK)" %}

```python
result = await session.call_tool(
    "audit_mandatory_question_force_analyze",
    {"instance_id": "ki_abc123", "question_id": "mq_jkl012"},
)
```

{% endtab %}

{% tab title="TypeScript (MCP SDK)" %}

```ts
const result = await client.callTool({
  name: "audit_mandatory_question_force_analyze",
  arguments: { instance_id: "ki_abc123", question_id: "mq_jkl012" },
});
```

{% endtab %}

{% tab title="Raw HTTP" %}

```bash
curl -X POST https://api-audit.kai-studio.ai/audit/mandatory-question/force-analyze \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"instance_id": "ki_abc123", "question_id": "mq_jkl012"}'
```

{% endtab %}
{% endtabs %}

## Missing subjects

Topics that should be covered but are absent from the document corpus. Workflow: list -> find detail -> list triggering questions -> answer companion questions -> generate companion document.

### audit\_missing\_subject\_list

Lists missing subjects for an instance.

**Input schema**

| Field         | Type               | Required | Description               |
| ------------- | ------------------ | -------- | ------------------------- |
| `instance_id` | string (`ki_*`)    | yes      | K-AI instance identifier. |
| `offset`      | integer (0–100000) | yes      | Number of items to skip.  |
| `limit`       | integer (1–1000)   | yes      | Maximum items to return.  |

**Output schema**

| Field                                              | Type            | Description                               |
| -------------------------------------------------- | --------------- | ----------------------------------------- |
| `response`                                         | array           | Missing subjects.                         |
| `response[].id`                                    | string (`ms_*`) | Missing-subject identifier.               |
| `response[].instance_id`                           | string (`ki_*`) | Owning instance.                          |
| `response[].state`                                 | string          | Current state.                            |
| `response[].extraproperties.compagnon_proposition` | string \| null  | Saved AI companion document text, if any. |

{% tabs %}
{% tab title="Python (MCP SDK)" %}

```python
result = await session.call_tool(
    "audit_missing_subject_list",
    {"instance_id": "ki_abc123", "offset": 0, "limit": 50},
)
```

{% endtab %}

{% tab title="TypeScript (MCP SDK)" %}

```ts
const result = await client.callTool({
  name: "audit_missing_subject_list",
  arguments: { instance_id: "ki_abc123", offset: 0, limit: 50 },
});
```

{% endtab %}

{% tab title="Raw HTTP" %}

```bash
curl -X POST https://api-audit.kai-studio.ai/audit/missing-subject/list \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"instance_id": "ki_abc123", "offset": 0, "limit": 50}'
```

{% endtab %}
{% endtabs %}

### audit\_missing\_subject\_find

Gets a missing subject detail.

**Input schema**

| Field         | Type            | Required | Description                 |
| ------------- | --------------- | -------- | --------------------------- |
| `instance_id` | string (`ki_*`) | yes      | K-AI instance identifier.   |
| `subject_id`  | string (`ms_*`) | yes      | Missing-subject identifier. |

**Output schema**

| Field                                            | Type            | Description                      |
| ------------------------------------------------ | --------------- | -------------------------------- |
| `response`                                       | object \| null  | Missing-subject detail, or null. |
| `response.id`                                    | string (`ms_*`) | Identifier.                      |
| `response.state`                                 | string          | Current state.                   |
| `response.extraproperties.compagnon_proposition` | string \| null  | Saved companion proposition.     |

{% tabs %}
{% tab title="Python (MCP SDK)" %}

```python
result = await session.call_tool(
    "audit_missing_subject_find",
    {"instance_id": "ki_abc123", "subject_id": "ms_mno345"},
)
```

{% endtab %}

{% tab title="TypeScript (MCP SDK)" %}

```ts
const result = await client.callTool({
  name: "audit_missing_subject_find",
  arguments: { instance_id: "ki_abc123", subject_id: "ms_mno345" },
});
```

{% endtab %}

{% tab title="Raw HTTP" %}

```bash
curl -X POST https://api-audit.kai-studio.ai/audit/missing-subject/find \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"instance_id": "ki_abc123", "subject_id": "ms_mno345"}'
```

{% endtab %}
{% endtabs %}

### audit\_missing\_subject\_list\_questions

Lists the questions that triggered a missing-subject cluster.

**Input schema**

| Field         | Type            | Required | Description                 |
| ------------- | --------------- | -------- | --------------------------- |
| `instance_id` | string (`ki_*`) | yes      | K-AI instance identifier.   |
| `subject_id`  | string (`ms_*`) | yes      | Missing-subject identifier. |

**Output schema**

| Field                 | Type            | Description          |
| --------------------- | --------------- | -------------------- |
| `response`            | array           | Subject-questions.   |
| `response[].id`       | string (`mq_*`) | Question identifier. |
| `response[].question` | string          | Question text.       |
| `response[].state`    | string          | Question state.      |

{% tabs %}
{% tab title="Python (MCP SDK)" %}

```python
result = await session.call_tool(
    "audit_missing_subject_list_questions",
    {"instance_id": "ki_abc123", "subject_id": "ms_mno345"},
)
```

{% endtab %}

{% tab title="TypeScript (MCP SDK)" %}

```ts
const result = await client.callTool({
  name: "audit_missing_subject_list_questions",
  arguments: { instance_id: "ki_abc123", subject_id: "ms_mno345" },
});
```

{% endtab %}

{% tab title="Raw HTTP" %}

```bash
curl -X POST https://api-audit.kai-studio.ai/audit/missing-subject/questions \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"instance_id": "ki_abc123", "subject_id": "ms_mno345"}'
```

{% endtab %}
{% endtabs %}

### audit\_missing\_subject\_set\_state

Updates the state of a missing subject.

**Input schema**

| Field         | Type            | Required | Description                 |
| ------------- | --------------- | -------- | --------------------------- |
| `instance_id` | string (`ki_*`) | yes      | K-AI instance identifier.   |
| `subject_id`  | string (`ms_*`) | yes      | Missing-subject identifier. |
| `state`       | string          | yes      | Target state.               |

**Output schema**

| Field      | Type | Description                                                |
| ---------- | ---- | ---------------------------------------------------------- |
| `response` | any  | Result of the transition (shape depends on the new state). |

{% tabs %}
{% tab title="Python (MCP SDK)" %}

```python
result = await session.call_tool(
    "audit_missing_subject_set_state",
    {"instance_id": "ki_abc123", "subject_id": "ms_mno345",
     "state": "MANAGED"},
)
```

{% endtab %}

{% tab title="TypeScript (MCP SDK)" %}

```ts
const result = await client.callTool({
  name: "audit_missing_subject_set_state",
  arguments: {
    instance_id: "ki_abc123",
    subject_id: "ms_mno345",
    state: "MANAGED",
  },
});
```

{% endtab %}

{% tab title="Raw HTTP" %}

```bash
curl -X POST https://api-audit.kai-studio.ai/audit/missing-subject/set-state \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"instance_id":"ki_abc123","subject_id":"ms_mno345","state":"MANAGED"}'
```

{% endtab %}
{% endtabs %}

### audit\_missing\_subject\_generate\_compagnon\_document

Produces an AI proposition for a document that would fill the gap identified by this missing subject. All companion questions must have been answered before generation can proceed.

**Input schema**

| Field         | Type            | Required | Description                 |
| ------------- | --------------- | -------- | --------------------------- |
| `instance_id` | string (`ki_*`) | yes      | K-AI instance identifier.   |
| `subject_id`  | string (`ms_*`) | yes      | Missing-subject identifier. |

**Output schema**

| Field      | Type   | Description                        |
| ---------- | ------ | ---------------------------------- |
| `response` | string | Generated companion document text. |

{% tabs %}
{% tab title="Python (MCP SDK)" %}

```python
result = await session.call_tool(
    "audit_missing_subject_generate_compagnon_document",
    {"instance_id": "ki_abc123", "subject_id": "ms_mno345"},
)
```

{% endtab %}

{% tab title="TypeScript (MCP SDK)" %}

```ts
const result = await client.callTool({
  name: "audit_missing_subject_generate_compagnon_document",
  arguments: { instance_id: "ki_abc123", subject_id: "ms_mno345" },
});
```

{% endtab %}

{% tab title="Raw HTTP" %}

```bash
curl -X POST https://api-audit.kai-studio.ai/audit/missing-subject/generate-compagnon-document \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"instance_id": "ki_abc123", "subject_id": "ms_mno345"}'
```

{% endtab %}
{% endtabs %}

## Full-audit broad review

The full-audit surface is a per-instance broad review independent of mandatory questions. **Lower priority than the conflict-first flow** — surface only after question-based conflicts are exhausted or when the expert explicitly asks for the broad audit.

### audit\_full\_audit\_conflict\_list

Lists full-audit conflicts for an instance. Default `state_in=['DETECTED']`. Allowed states: `DETECTED`, `REDETECTED`, `MANAGED`, `IGNORED`, `DISAPPEARED`. Pass `state_in=[]` for all states except `DISAPPEARED`. Pass `only_linked_to_question=true` to get just the priority subset — conflicts linked to a mandatory question, flagged `is_important` (see [Priority](#priority)).

**Input schema**

| Field                     | Type                   | Required           | Description                                                                              |
| ------------------------- | ---------------------- | ------------------ | ---------------------------------------------------------------------------------------- |
| `instance_id`             | string (`ki_*`)        | yes                | K-AI instance identifier.                                                                |
| `offset`                  | integer (0–100000)     | no (default 0)     | Number of conflicts to skip.                                                             |
| `limit`                   | integer (1–1000)       | no (default 500)   | Maximum conflicts to return.                                                             |
| `state_in`                | array of state \| null | no                 | Defaults to `['DETECTED']`.                                                              |
| `only_linked_to_question` | boolean                | no (default false) | When `true`, return only conflicts linked to a mandatory question (the priority subset). |

**Output schema**

| Field                         | Type                     | Description                                                                            |
| ----------------------------- | ------------------------ | -------------------------------------------------------------------------------------- |
| `response`                    | array                    | Full-audit conflicts.                                                                  |
| `response[].id`               | string (`fc_*`)          | Full-audit conflict identifier.                                                        |
| `response[].state`            | enum                     | `DETECTED` \| `REDETECTED` \| `MANAGED` \| `IGNORED` \| `DISAPPEARED`.                 |
| `response[].subject`          | string \| null           | Subject of the conflict.                                                               |
| `response[].explanation`      | string \| null           | Explanation of the conflict.                                                           |
| `response[].documents`        | array                    | Involved documents (`doc_id`, `document_name`, `document_url`).                        |
| `response[].linked_questions` | array of string (`mq_*`) | Mandatory questions this conflict is linked to.                                        |
| `response[].is_important`     | boolean                  | `true` when `linked_questions` is non-empty — shares priority with question conflicts. |

{% tabs %}
{% tab title="Python (MCP SDK)" %}

```python
result = await session.call_tool(
    "audit_full_audit_conflict_list",
    {"instance_id": "ki_abc123", "offset": 0, "limit": 100},
)
```

{% endtab %}

{% tab title="TypeScript (MCP SDK)" %}

```ts
const result = await client.callTool({
  name: "audit_full_audit_conflict_list",
  arguments: { instance_id: "ki_abc123", offset: 0, limit: 100 },
});
```

{% endtab %}

{% tab title="Raw HTTP" %}

```bash
curl -X POST https://api-audit.kai-studio.ai/audit/full-audit/list \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"instance_id": "ki_abc123", "offset": 0, "limit": 100}'
```

{% endtab %}
{% endtabs %}

### audit\_full\_audit\_conflict\_get

Returns subject, explanation, involved documents (hydrated with `document_name` + `document_url`), companion questions (`compagnon_questions`), the expert answer if saved, and structured per-document recommendations (`compagnon_recommendations`) if generated. Present companion questions to the expert before collecting an answer.

**Input schema**

| Field         | Type            | Required | Description                     |
| ------------- | --------------- | -------- | ------------------------------- |
| `instance_id` | string (`ki_*`) | yes      | K-AI instance identifier.       |
| `conflict_id` | string (`fc_*`) | yes      | Full-audit conflict identifier. |

**Output schema**

| Field                       | Type                     | Description                                                              |
| --------------------------- | ------------------------ | ------------------------------------------------------------------------ |
| `response.id`               | string (`fc_*`)          | Conflict identifier.                                                     |
| `response.state`            | enum                     | Current state.                                                           |
| `response.subject`          | string \| null           | Subject of the conflict.                                                 |
| `response.explanation`      | string \| null           | Explanation.                                                             |
| `response.documents`        | array                    | Involved documents.                                                      |
| `response.linked_questions` | array of string (`mq_*`) | Mandatory questions this conflict is linked to.                          |
| `response.is_important`     | boolean                  | `true` when `linked_questions` is non-empty.                             |
| `response.extraproperties`  | object                   | Includes `compagnon_questions` and optional `compagnon_recommendations`. |

{% tabs %}
{% tab title="Python (MCP SDK)" %}

```python
result = await session.call_tool(
    "audit_full_audit_conflict_get",
    {"instance_id": "ki_abc123", "conflict_id": "fc_pqr678"},
)
```

{% endtab %}

{% tab title="TypeScript (MCP SDK)" %}

```ts
const result = await client.callTool({
  name: "audit_full_audit_conflict_get",
  arguments: { instance_id: "ki_abc123", conflict_id: "fc_pqr678" },
});
```

{% endtab %}

{% tab title="Raw HTTP" %}

```bash
curl -X POST https://api-audit.kai-studio.ai/audit/full-audit/detail \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"instance_id": "ki_abc123", "conflict_id": "fc_pqr678"}'
```

{% endtab %}
{% endtabs %}

### audit\_full\_audit\_conflict\_set\_answer

Records the expert resolution and returns per-document modification recommendations inline. Sync LLM call (\~5s typical, \~10s p99). After receiving the response, render `recommendations` as a markdown table (`Document | Action`) using `document_url` to turn the document name into a link, and ask the expert whether each modification was applied before calling `audit_full_audit_conflict_close` or `_ignore`. If `recommendations` is empty, the LLM crew failed for this conflict — offer to retry by calling this endpoint again.

**Input schema**

| Field         | Type            | Required | Description                     |
| ------------- | --------------- | -------- | ------------------------------- |
| `instance_id` | string (`ki_*`) | yes      | K-AI instance identifier.       |
| `conflict_id` | string (`fc_*`) | yes      | Full-audit conflict identifier. |
| `answer`      | string          | yes      | Expert resolution text.         |

**Output schema**

| Field                                      | Type            | Description                                |
| ------------------------------------------ | --------------- | ------------------------------------------ |
| `response.conflict`                        | object          | Updated full-audit conflict.               |
| `response.recommendations`                 | array           | Per-document modification recommendations. |
| `response.recommendations[].document_id`   | string (`kd_*`) | Target document.                           |
| `response.recommendations[].document_name` | string \| null  | Document name.                             |
| `response.recommendations[].document_url`  | string \| null  | Document URL for citation.                 |
| `response.recommendations[].type`          | string          | Recommendation type.                       |
| `response.recommendations[].action`        | string          | Recommended action text.                   |

{% tabs %}
{% tab title="Python (MCP SDK)" %}

```python
result = await session.call_tool(
    "audit_full_audit_conflict_set_answer",
    {"instance_id": "ki_abc123", "conflict_id": "fc_pqr678",
     "answer": "The Brussels office is the EU headquarters."},
)
```

{% endtab %}

{% tab title="TypeScript (MCP SDK)" %}

```ts
const result = await client.callTool({
  name: "audit_full_audit_conflict_set_answer",
  arguments: {
    instance_id: "ki_abc123",
    conflict_id: "fc_pqr678",
    answer: "The Brussels office is the EU headquarters.",
  },
});
```

{% endtab %}

{% tab title="Raw HTTP" %}

```bash
curl -X POST https://api-audit.kai-studio.ai/audit/full-audit/set-expert-answer \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"instance_id":"ki_abc123","conflict_id":"fc_pqr678","answer":"The Brussels office is the EU headquarters."}'
```

{% endtab %}
{% endtabs %}

### audit\_full\_audit\_conflict\_ignore

Marks a full-audit conflict as `IGNORED`. The expert chose not to resolve this conflict.

**Input schema**

| Field         | Type            | Required | Description                     |
| ------------- | --------------- | -------- | ------------------------------- |
| `instance_id` | string (`ki_*`) | yes      | K-AI instance identifier.       |
| `conflict_id` | string (`fc_*`) | yes      | Full-audit conflict identifier. |

**Output schema**

| Field              | Type    | Description      |
| ------------------ | ------- | ---------------- |
| `response.success` | boolean | True on success. |

{% tabs %}
{% tab title="Python (MCP SDK)" %}

```python
result = await session.call_tool(
    "audit_full_audit_conflict_ignore",
    {"instance_id": "ki_abc123", "conflict_id": "fc_pqr678"},
)
```

{% endtab %}

{% tab title="TypeScript (MCP SDK)" %}

```ts
const result = await client.callTool({
  name: "audit_full_audit_conflict_ignore",
  arguments: { instance_id: "ki_abc123", conflict_id: "fc_pqr678" },
});
```

{% endtab %}

{% tab title="Raw HTTP" %}

```bash
curl -X POST https://api-audit.kai-studio.ai/audit/full-audit/ignore \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"instance_id": "ki_abc123", "conflict_id": "fc_pqr678"}'
```

{% endtab %}
{% endtabs %}

### audit\_full\_audit\_conflict\_close

Closes (marks `MANAGED`) a full-audit conflict. Call only after the expert has confirmed every modification listed in the recommendations from `audit_full_audit_conflict_set_answer` was applied.

**Input schema**

| Field         | Type            | Required | Description                     |
| ------------- | --------------- | -------- | ------------------------------- |
| `instance_id` | string (`ki_*`) | yes      | K-AI instance identifier.       |
| `conflict_id` | string (`fc_*`) | yes      | Full-audit conflict identifier. |

**Output schema**

| Field              | Type    | Description      |
| ------------------ | ------- | ---------------- |
| `response.success` | boolean | True on success. |

{% tabs %}
{% tab title="Python (MCP SDK)" %}

```python
result = await session.call_tool(
    "audit_full_audit_conflict_close",
    {"instance_id": "ki_abc123", "conflict_id": "fc_pqr678"},
)
```

{% endtab %}

{% tab title="TypeScript (MCP SDK)" %}

```ts
const result = await client.callTool({
  name: "audit_full_audit_conflict_close",
  arguments: { instance_id: "ki_abc123", conflict_id: "fc_pqr678" },
});
```

{% endtab %}

{% tab title="Raw HTTP" %}

```bash
curl -X POST https://api-audit.kai-studio.ai/audit/full-audit/close \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"instance_id": "ki_abc123", "conflict_id": "fc_pqr678"}'
```

{% endtab %}
{% endtabs %}

## Not exposed on MCP (REST-only)

The following audit REST operations are intentionally excluded from the MCP surface. They power the K-AI Audit web app, admin flows, or CronJobs — exposing them to a host LLM would invite destructive or high-volume calls without expert oversight. Use the REST API directly when you need them.

**Instance setup and admin (browser-only):**

* `audit_instance_list_for_user` · `audit_instance_get` · `audit_instance_get_kai_instances` — instance discovery & K-AI credentials lookup.
* `audit_instance_update_step` · `audit_instance_update_configuration` — workflow state transitions and configuration edits.

**User membership (admin only):**

* `audit_user_get_users` · `audit_user_list_instances` — membership listing.
* `audit_user_add` · `audit_user_remove` — add/remove user on an instance.
* `audit_user_set_admin` · `audit_user_set_normal` — promote/demote.
* `audit_user_is_admin` — admin check used by the K-AI Audit web app.

**Documents (high-volume queries served by REST):**

* `audit_documents_list` · `audit_documents_list_with_state` — paginated browse with filters.
* `audit_documents_count` — indexation progress monitoring.
* `audit_documents_set_owner` — owner assignment (admin only).

**Duplicates (out of conflict-first scope):**

* `audit_duplicate_list` — duplicate cluster listing.
* `audit_duplicate_set_managed` — mark a cluster as managed.

**Mandatory question writes (driven by the K-AI Audit web app):**

* `audit_mandatory_question_set_answer` — expert resolution at the question level (experts resolve via `audit_question_conflict_set_answer` instead).
* `audit_mandatory_question_set_managed` · `audit_mandatory_question_set_ignored` — question-level state writes.

**Question-conflict analytics:**

* `audit_conflict_get_top_collaborators` — top collaborators sharing conflicts.

**Full-audit (UI helpers and admin transitions):**

* `audit_full_audit_have_to_show` — UI helper that returns whether the full-audit panel is available.
* `audit_full_audit_set_state` — direct state transition (reopen) used by the K-AI Audit web app; the MCP surface uses `audit_full_audit_conflict_close` / `_ignore` instead.

**Stats (dashboard cards on REST):**

* `audit_stats_get_daily` · `audit_stats_get_user` · `audit_stats_get_filtered` — daily, per-user, and aggregated counters.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://k-ai.gitbook.io/knowledge-ai/k-ai-mcp/audit-tools.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.