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

# Tools

Tools are grouped by mode. Runtime tools are always available. Configure tools require configure or frontend mode.

## Runtime Tools

Available in all modes.

### `list_workspaces`

List workspaces the current user has access to. This is the first tool called in any session.

| Parameter | Type   | Required | Description                  |
| --------- | ------ | -------- | ---------------------------- |
| `search`  | string | No       | Case-insensitive name filter |

***

### `set_workspace`

Set the active workspace for the session.

| Parameter     | Type   | Required | Description                         |
| ------------- | ------ | -------- | ----------------------------------- |
| `workspaceId` | string | Yes      | Workspace ID from `list_workspaces` |

***

### `list_modules`

List all discoverable modules in the active workspace.

| Parameter     | Type   | Required | Description                    |
| ------------- | ------ | -------- | ------------------------------ |
| `workspaceId` | string | No       | Overrides the active workspace |

***

### `list_entries`

Query entries with filters, sorting, and pagination. Results may vary over time as other users modify entries — the call itself has no side effects.

| Parameter       | Type            | Required | Description                     |
| --------------- | --------------- | -------- | ------------------------------- |
| `module`        | string          | Yes      | Module name                     |
| `state`         | string          | No       | Filter by state name            |
| `search`        | string          | No       | Free-text search                |
| `filters`       | object          | No       | Field-level filters (see below) |
| `sortBy`        | string          | No       | Field name to sort by           |
| `sortDirection` | `asc` \| `desc` | No       | Default: `asc`                  |
| `currentPage`   | number          | No       | 0-based page number             |
| `pageSize`      | number          | No       | Default 50, max 500             |
| `workspaceId`   | string          | No       | Overrides the active workspace  |

<details>

<summary>Filter syntax</summary>

Filter keys are field display names. Values can be:

* A plain value for equality: `{ "Status": "Active" }`
* An operator object: `{ "Amount": { "min": 1000, "max": 5000 } }`
* `{ "or": [...] }` for OR conditions
* Multiple keys are AND-ed together

Supported operators: `contains`, `startsWith`, `endsWith`, `min`, `max`, `above`, `below`, `between`, `after`, `before`, `empty`, `exists`, `yes`, `no`, `is`, `not`, `excludes`

Use `"me"` as the value for User fields to match the current user.

</details>

***

### `get_entry`

Read a single entry by ID.

| Parameter     | Type             | Required | Description                    |
| ------------- | ---------------- | -------- | ------------------------------ |
| `module`      | string           | Yes      | Module name                    |
| `entryId`     | string \| number | Yes      | Entry ID                       |
| `workspaceId` | string           | No       | Overrides the active workspace |

Returns: current field values, state, audit metadata, and available activities.

***

### `get_form`

Get the form fields, current values, and options for an activity. Always call this before `submit_activity`.

| Parameter     | Type             | Required | Description                                                |
| ------------- | ---------------- | -------- | ---------------------------------------------------------- |
| `module`      | string           | Yes      | Module name                                                |
| `activity`    | string           | No       | Activity name. Default: `create`                           |
| `entryId`     | string \| number | No       | Required for edit/view/custom activities. Omit for create. |
| `workspaceId` | string           | No       | Overrides the active workspace                             |

Returns: required fields, field types, valid options, default values, and the activity's `confidence_threshold`.

***

### `submit_activity`

Perform an activity on a module entry: create, edit, delete, changeStatus, comment, duplicate, manage, or any custom activity. Requires the `ai` object for full traceability. Always call `get_form` first.

| Parameter     | Type             | Required | Description                        |
| ------------- | ---------------- | -------- | ---------------------------------- |
| `module`      | string           | Yes      | Module name                        |
| `activity`    | string           | No       | Activity name. Default: `create`   |
| `entryId`     | string \| number | No       | Omit for create                    |
| `entryIds`    | array            | No       | For bulk operations                |
| `input`       | object           | No       | Field values keyed by display name |
| `state`       | string           | No       | Target state name                  |
| `comment`     | string           | No       | Comment to add                     |
| `assignees`   | string\[]        | No       | Usernames to assign                |
| `due`         | string           | No       | Due date in ISO 8601               |
| `ai`          | object           | **Yes**  | AI traceability object (see below) |
| `workspaceId` | string           | No       | Overrides the active workspace     |

<details>

<summary>The `ai` object (required)</summary>

Every `submit_activity` call must include an `ai` object:

```json
{
  "reasoning": "User requested approval of leave request LR-0055.",
  "model": "claude-sonnet-4-6",
  "confidence": 0.95,
  "sources": [
    { "type": "user_message", "excerpt": "Approve leave request LR-0055" }
  ]
}
```

If `confidence` is below the activity's `confidence_threshold`, the state transition is suppressed and the entry is flagged for human review.

</details>

<details>

<summary>Field value shapes for `input`</summary>

| Field type       | Shape                                                                       |
| ---------------- | --------------------------------------------------------------------------- |
| File / Image     | `{ "name": "photo.jpg", "path": "/s/guid/photo.jpg" }`                      |
| Module reference | `{ "value": "Display Name", "id": "entry-id" }`                             |
| User             | `{ "value": "Full Name", "id": "user-id", "username": "user@example.com" }` |
| Plural variants  | Use arrays of the above shapes                                              |

</details>

***

### `submit_activities`

Bulk variant of `submit_activity` — same module and activity applied to multiple entries in a single call. Use this instead of multiple sequential `submit_activity` calls when creating or editing many rows at once.

| Parameter     | Type    | Required | Description                                                                                                       |
| ------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `module`      | string  | Yes      | Module name                                                                                                       |
| `activity`    | string  | No       | Activity name. Default: `create`                                                                                  |
| `ai`          | object  | Yes      | Default AI traceability applied to every item that does not supply its own                                        |
| `items`       | array   | Yes      | 1–100 items (see below)                                                                                           |
| `confirmed`   | boolean | No       | Required when activity is `changeStatus`, any item supplies a `state` override, or the activity actor is `hybrid` |
| `workspaceId` | string  | No       | Overrides the active workspace                                                                                    |

**Each item in `items`:**

| Field       | Type             | Description                                                                                   |
| ----------- | ---------------- | --------------------------------------------------------------------------------------------- |
| `entryId`   | string \| number | Omit for create operations                                                                    |
| `input`     | object           | Field values keyed by display name — same shape as `submit_activity.input`                    |
| `state`     | string           | Per-item target state override                                                                |
| `comment`   | string           | Comment to add                                                                                |
| `assignees` | string\[]        | Usernames                                                                                     |
| `due`       | string           | ISO 8601 due date                                                                             |
| `ai`        | object           | Per-item AI override. Wholly replaces the top-level `ai` for this item — no partial merge.    |
| `clientRef` | string           | Optional caller-supplied ID echoed back in results, useful for correlating items to your plan |

Items run sequentially and fail-soft — one item's failure does not abort the rest. Per-item outcomes (success/failure, entryId, flagged) are returned in `results`.

{% hint style="warning" %}
Max 100 items per request. For larger batches, chunk into multiple calls. The same guardrails as `submit_activity` apply: `actor=human` rejects the whole batch; `actor=hybrid`, `changeStatus`, or any `state` override requires `confirmed: true`.
{% endhint %}

***

### `get_entry_history`

Get the full audit trail and comments for an entry.

| Parameter     | Type             | Required | Description                      |
| ------------- | ---------------- | -------- | -------------------------------- |
| `module`      | string           | Yes      | Module name                      |
| `entryId`     | string \| number | Yes      | Entry ID                         |
| `page`        | number           | No       | 0-based page (50 items per page) |
| `workspaceId` | string           | No       | Overrides the active workspace   |

***

### `request_upload_url`

Request a pre-signed S3 upload URL. Use this for all file uploads (up to 500 MB). Follow with a PUT to the URL, then call `confirm_upload`.

| Parameter     | Type   | Required | Description                                        |
| ------------- | ------ | -------- | -------------------------------------------------- |
| `module`      | string | Yes      | Module name (scopes file to module storage)        |
| `fileName`    | string | Yes      | Original filename including extension              |
| `contentType` | string | No       | MIME type. Must match the PUT Content-Type header. |
| `fileSize`    | number | Yes      | File size in bytes (max 524,288,000)               |
| `workspaceId` | string | No       | Overrides the active workspace                     |

***

### `confirm_upload`

Confirm a presigned upload completed. Call after successfully PUTting the file to the `uploadUrl`.

| Parameter     | Type   | Required | Description                                    |
| ------------- | ------ | -------- | ---------------------------------------------- |
| `s3Key`       | string | Yes      | The `s3Key` returned from `request_upload_url` |
| `workspaceId` | string | No       | Overrides the active workspace                 |

Returns: `{ url, filename, mimeType, size }` — use `url` as the `path` in File/Image field values.

***

### `download_file`

Request a pre-signed download URL for an existing file (1-hour TTL).

| Parameter     | Type   | Required | Description                          |
| ------------- | ------ | -------- | ------------------------------------ |
| `moduleName`  | string | Yes      | Module name                          |
| `guid`        | string | Yes      | Short ID from the file's stored path |
| `fileName`    | string | Yes      | Original filename                    |
| `workspaceId` | string | No       | Overrides the active workspace       |

***

### `upload_file`

**Fallback only.** Upload a file via base64 encoding (max 50 MB). Use `request_upload_url` + `confirm_upload` instead. Only use this if the presigned flow has failed.

| Parameter     | Type   | Required | Description                         |
| ------------- | ------ | -------- | ----------------------------------- |
| `module`      | string | Yes      | Module name                         |
| `name`        | string | Yes      | Original filename                   |
| `file`        | string | Yes      | Base64-encoded file content         |
| `mimeType`    | string | No       | Default: `application/octet-stream` |
| `workspaceId` | string | No       | Overrides the active workspace      |

***

### `switch_mode`

Switch the active tool surface.

| Parameter | Type                                   | Required | Description |
| --------- | -------------------------------------- | -------- | ----------- |
| `mode`    | `runtime` \| `configure` \| `frontend` | Yes      | Target mode |

***

## Configure Tools

Available in **configure** and **frontend** modes.

### `get_module_schema`

Get the schema for a module. Use `tier=basic` for fields and states only; `tier=extended` to also include activities and flows.

| Parameter     | Type                  | Required | Description                    |
| ------------- | --------------------- | -------- | ------------------------------ |
| `module`      | string                | Yes      | Module name                    |
| `tier`        | `basic` \| `extended` | No       | Default: `basic`               |
| `workspaceId` | string                | No       | Overrides the active workspace |

***

### `get_module_canvas`

Fetch the full module definition with stable IDs for round-trip editing. Use before `update_module` to preserve IDs and enable renaming without data loss.

| Parameter     | Type   | Required | Description                    |
| ------------- | ------ | -------- | ------------------------------ |
| `module`      | string | Yes      | Module name or numeric ID      |
| `workspaceId` | string | No       | Overrides the active workspace |

***

### `design_workflow`

Generate a scaffolded `ModuleSchema` template from a natural language description. Runs locally — no API call.

| Parameter     | Type   | Required | Description                                                                                                           |
| ------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `description` | string | Yes      | Natural language description of the workflow                                                                          |
| `industry`    | enum   | No       | One of: `financial_services`, `healthcare`, `legal`, `hr`, `procurement`, `it_service`, `general`. Default: `general` |

***

### `validate_design`

Validate a module schema against all FACTSOps rules before creating or updating. Runs locally — no API call.

| Parameter | Type                 | Required | Description                                                                   |
| --------- | -------------------- | -------- | ----------------------------------------------------------------------------- |
| `schema`  | object               | Yes      | A complete or partial `ModuleSchema` object                                   |
| `mode`    | `create` \| `update` | No       | Default: `create`. Use `update` when validating a partial schema for merging. |

***

### `create_module`

Create a new module in the workspace. Always call `validate_design` first.

| Parameter     | Type   | Required | Description                                           |
| ------------- | ------ | -------- | ----------------------------------------------------- |
| `name`        | string | Yes      | Module name                                           |
| `icon`        | string | No       | Emoji identifier                                      |
| `description` | string | No       | Module description                                    |
| `information` | array  | No       | Field definitions                                     |
| `states`      | array  | No       | Workflow states (omit for record list modules)        |
| `activities`  | array  | No       | Activities (omit for record list modules)             |
| `flows`       | array  | No       | State transition rules (omit for record list modules) |
| `workspaceId` | string | No       | Overrides the active workspace                        |

Requires: Administrator, Consultant, or Workspace Admin role.

***

### `update_module`

Update an existing module by merging changes. Items matched by stable ID enable renaming without data loss. Always call `get_module_canvas` first to obtain stable IDs, then `validate_design` before submitting.

{% hint style="warning" %}
This tool is destructive. Removing fields, states, or activities may orphan stored values in existing entries and cannot be undone. The AI will warn you before applying removals.
{% endhint %}

| Parameter     | Type   | Required | Description                                 |
| ------------- | ------ | -------- | ------------------------------------------- |
| `id`          | string | Yes      | Module ID from `get_module_canvas`          |
| `name`        | string | No       | New module name (for renaming)              |
| `icon`        | string | No       | New emoji identifier                        |
| `description` | string | No       | New description                             |
| `information` | array  | No       | Updated field definitions (matched by `id`) |
| `states`      | array  | No       | Updated states (matched by `id`)            |
| `activities`  | array  | No       | Updated activities (matched by `id`)        |
| `flows`       | array  | No       | Updated flows                               |
| `workspaceId` | string | No       | Overrides the active workspace              |

Omitted sections are left unchanged.