# 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.


---

# Agent Instructions: 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:

```
GET https://inistate.gitbook.io/home/mcp-integration/reference/tools.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.