> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.getmasset.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getmasset.com/_mcp/server.

# Tools

The Masset MCP Server exposes 37 tools spanning search, asset details, asset management, sharing, activity, discovery, content rooms, content requests, and training. Most tools are read-only; the asset management, asset-sharing, content room, content request, and training mutation tools modify state in your Masset workspace. AI clients auto-discover the available tools when a connection is established. The toolset will continue to grow to include more Masset functionality over time.

## Search tools

These tools allow you to find assets in your Masset library using different search strategies.

### `asset_search`

Search for assets by keyword or meaning and return ranked results with metadata. This is the primary search interface — most clients should use this tool for search workflows. Use `get_search_context` first when the request depends on taxonomy terms (tags, collections) to understand available values.

| Parameter                | Type    | Required | Description                                                                                                                          |
| ------------------------ | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `query`                  | string  | No       | Search query (minimum 2 characters). Optional if filters are provided.                                                               |
| `mode`                   | string  | No       | Search mode: `all` (default), `keyword`, or `semantic`.                                                                              |
| `orderBy`                | string  | No       | Sort order: `relevance` (default), `updated_at_desc`, `created_at_desc`, `name_asc`, `name_desc`.                                    |
| `filters`                | object  | No       | Filter object with optional fields: `tags`, `collections`, `mimeTypes`, `createdAfter`, `createdBefore`, `isLinkedAsset`.            |
| `limit`                  | integer | No       | Maximum results to return (default 20, max 50).                                                                                      |
| `includeMetadata`        | boolean | No       | Include enriched metadata in each result (default `true`).                                                                           |
| `includeContentSnippets` | boolean | No       | Include text snippets in match pointers (default `false`).                                                                           |
| `deletionScope`          | string  | No       | Which assets to search: `ACTIVE` (default) or `TRASHED` (soft-deleted). `TRASHED` is admin-only; non-admins are limited to `ACTIVE`. |

**Required scope:** `mcp:asset_read`

### `keyword_search`

> **Note**
>
> **Agentic use.** This tool is primarily intended for agentic use cases (like Codex or Claude Code) that have the ability to repeatedly call tools.

Search for assets by keyword. Performs case-insensitive substring matching across asset names, descriptions, file names, tag names, collection names, and detected object labels, with full-text search on content (plus substring fallback when needed). Returns a list of matching asset IDs. Use `get_asset_metadata` to retrieve full details for the returned IDs.

| Parameter       | Type    | Required | Description                                                                                                                          |
| --------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `query`         | string  | Yes      | The search query (minimum 2 characters).                                                                                             |
| `limit`         | integer | No       | Maximum results to return (default 100, max 500).                                                                                    |
| `deletionScope` | string  | No       | Which assets to search: `ACTIVE` (default) or `TRASHED` (soft-deleted). `TRASHED` is admin-only; non-admins are limited to `ACTIVE`. |

**Required scope:** `mcp:asset_read`

### `semantic_search`

> **Note**
>
> **Agentic use.** This tool is primarily intended for agentic use cases (like Codex or Claude Code) that have the ability to repeatedly call tools.

Search for assets using semantic (meaning-based) search. Finds content that is conceptually related to the query, even if it doesn't contain the exact keywords. Returns ranked chunks of content with their asset IDs and relevance scores.

| Parameter       | Type    | Required | Description                                                                                                                          |
| --------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `query`         | string  | Yes      | The search query. Natural language works best.                                                                                       |
| `limit`         | integer | No       | Maximum result chunks to return (default 50, max 200).                                                                               |
| `deletionScope` | string  | No       | Which assets to search: `ACTIVE` (default) or `TRASHED` (soft-deleted). `TRASHED` is admin-only; non-admins are limited to `ACTIVE`. |

**Required scope:** `mcp:asset_read`

### `find_similar_assets`

Find assets similar to one or more source assets, ranked by similarity. Similarity blends the source assets' embedded content (text and visual) with shared tags, so it works across documents, images, videos, presentations, and websites. When multiple source asset IDs are provided, results are similar to the combined theme of all sources. Source assets that have no embedded content yet (for example, still processing) are reported back in `sourceAssetIdsWithoutEmbeddings`. Use `get_asset_metadata` to retrieve full details for the returned asset IDs. Results are limited to assets the current user has permission to view.

| Parameter             | Type      | Required | Description                                                                                         |
| --------------------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `assetIds`            | string\[] | Yes      | Source asset IDs (UUIDs) to find similar assets for (max 10).                                       |
| `limit`               | integer   | No       | Maximum similar assets to return (default 20, max 50).                                              |
| `matchLevel`          | string    | No       | Match strictness: `STRICT` (only very close matches), `BALANCED` (default), or `BROAD` (wider net). |
| `includeSourceAssets` | boolean   | No       | Include the source asset(s) first in the results (default `true`).                                  |

**Required scope:** `mcp:asset_read`

### `asset_analytics_search`

Rank assets by an analytics metric and return the top results. Use this for requests like "top downloaded assets", "most viewed content last month", or "how many times was this asset viewed this year". You can scope analytics to a specific subset of assets by passing `assetIds` from `asset_search`.

| Parameter         | Type      | Required | Description                                                                          |
| ----------------- | --------- | -------- | ------------------------------------------------------------------------------------ |
| `metric`          | string    | Yes      | Metric to rank by: `downloads`, `views`, or `shares`.                                |
| `start`           | string    | No       | Start of the analytics window in ISO 8601 format. Omit for all-time.                 |
| `end`             | string    | No       | End of the analytics window in ISO 8601 format. Omit for all-time.                   |
| `audience`        | string    | No       | Audience filter: `external`, `internal`, or `both`.                                  |
| `assetIds`        | string\[] | No       | List of asset IDs (UUIDs) to limit analytics to (max 50). Omit for global analytics. |
| `limit`           | integer   | No       | Maximum results to return (default 20, max 50).                                      |
| `offset`          | integer   | No       | Number of results to skip (default 0).                                               |
| `includeMetadata` | boolean   | No       | Include enriched metadata in each result (default `true`).                           |

**Required scope:** `mcp:asset_read` + analytics permissions

### `search_query_analytics`

Report what people search for in Masset and which searches return no results. Covers the web search page, the Slack `/masset-search` command, MCP search tools, Myca, and content room assistants. Use this for requests like "what are people searching for that returns nothing?", "who searched for pricing sheet?", or "what did Myca fail to find this week?". Admin only.

The `view` parameter selects what the tool returns:

* **`top_queries`** (default) — queries grouped by normalized text, sorted by zero-result count. Pass `query` to filter by text.
* **`query_events`** — individual searches for one query (`query` required), including who searched and the rephrasing that worked, if any.
* **`unanswered_ai_turns`** — AI assistant turns where every search the assistant tried returned nothing.
* **`summary`** — totals, zero-result rate, how many zero-result searches were never followed by a successful search, and AI turns where every search came back empty. Includes `dataAvailableSince`, the date search tracking began.

> **Note**
>
> AI rows record the query the assistant generated, not the user's own words. To confirm a content gap, re-run the query with `asset_search`.

| Parameter         | Type      | Required | Description                                                                                                         |
| ----------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
| `view`            | string    | No       | View to return: `top_queries` (default), `query_events`, `unanswered_ai_turns`, or `summary`.                       |
| `start`           | string    | No       | Start of the window in ISO 8601 format. Defaults to 30 days before `end`.                                           |
| `end`             | string    | No       | End of the window in ISO 8601 format. Defaults to now. The window may span at most 366 days.                        |
| `sources`         | string\[] | No       | Only include these sources: `web`, `slack`, `mcp`, `myca`, `content_room`. Defaults to all.                         |
| `query`           | string    | No       | For `top_queries`, filters to queries containing this text. For `query_events`, the query to drill into (required). |
| `zeroResultsOnly` | boolean   | No       | Only include searches that returned no results (default `true`).                                                    |
| `includeFiltered` | boolean   | No       | Include searches narrowed by filters such as tags or favorites (default `false`).                                   |
| `sortBy`          | string    | No       | Sort for `top_queries`: `zero_results` (default), `unrecovered`, `searches`, `zero_result_rate`, or `recent`.       |
| `limit`           | integer   | No       | Maximum results to return (default 20, max 50).                                                                     |
| `offset`          | integer   | No       | Number of results to skip (default 0).                                                                              |

**Required scope:** `mcp` + search analytics permissions (admins only)

## Asset detail tools

These tools retrieve detailed information about specific assets by their IDs.

### `get_asset_metadata`

Retrieve detailed metadata for a list of assets by their IDs. Returns enriched asset information including name, description, file type, size, properties, tags, colors, and more. Maximum of 50 asset IDs per request.

| Parameter  | Type      | Required | Description                                                  |
| ---------- | --------- | -------- | ------------------------------------------------------------ |
| `assetIds` | string\[] | Yes      | List of asset IDs (UUIDs) to retrieve metadata for (max 50). |

**Required scope:** `mcp:asset_read`

### `get_asset_content`

Retrieve the text content of assets by their IDs. Returns extracted text content for each asset. Content is truncated to 50,000 characters per piece with a truncation indicator. Maximum of 10 asset IDs per request.

Content types include:

* Raw text
* Summaries
* OCR text
* Transcriptions

| Parameter  | Type      | Required | Description                                                 |
| ---------- | --------- | -------- | ----------------------------------------------------------- |
| `assetIds` | string\[] | Yes      | List of asset IDs (UUIDs) to retrieve content for (max 10). |

**Required scope:** `mcp:asset_content_read`

### `get_asset_preview`

Fetch a JPEG preview image for an asset. Returns text context plus a base64-encoded image that can be displayed inline in AI conversations.

| Parameter | Type   | Required | Description                             |
| --------- | ------ | -------- | --------------------------------------- |
| `assetId` | string | Yes      | Asset ID (UUID) to fetch a preview for. |

**Required scope:** `mcp:asset_read`

## Asset management tools

These tools create and modify assets in your Masset library. Unlike the read-only tools above, they change the contents of your workspace.

### `asset_upload`

Upload a new Masset asset. The tool supports three modes, selected with the `mode` parameter:

* **`base64`** — for files up to 25 MB decoded. Provide `fileBase64` and the asset is created synchronously after server-side analysis.
* **`request_upload_url`** — for larger files. The tool returns a one-time raw `PUT` `uploadUrl`, the required headers, and an `expiresAt` timestamp 15 minutes out. The `PUT` response returns the finalized asset after server-side analysis.
* **`external_link`** — registers an external URL as an asset with no file bytes. Provide `url` and optionally `name` and `description`. The asset is created and published synchronously.

| Parameter     | Type   | Required | Description                                                               |
| ------------- | ------ | -------- | ------------------------------------------------------------------------- |
| `mode`        | string | Yes      | Upload mode: `base64`, `request_upload_url`, or `external_link`.          |
| `fileBase64`  | string | No       | Base64-encoded file content. Required when `mode=base64`.                 |
| `url`         | string | No       | External URL to register as an asset. Required when `mode=external_link`. |
| `name`        | string | No       | Display name for the `external_link` asset. Defaults to "External asset". |
| `description` | string | No       | Description for the `external_link` asset.                                |

The response `status` is one of `created`, `upload_url_created`, `rejected`, or `failed`.

**Required scope:** `mcp` + asset management permissions

### `asset_new_version`

Replace the file behind an existing Masset asset with a new version. The asset keeps its ID, name, description, tags, collections, sharing, and analytics history — only the file and the properties derived from it change. To change an asset's name, description, or tags without touching its file, use `update_asset` instead.

The tool supports two modes, selected with the `mode` parameter:

* **`base64`** — for files up to 25 MB decoded. Provide `assetId` and `fileBase64`.
* **`request_upload_url`** — for larger files. The tool returns a one-time raw `PUT` `uploadUrl` bound to that asset, with a 15 minute expiry. The `PUT` response returns the updated asset.

> **Warning**
>
> The previous file is **not** retained and cannot be restored. This does not change the asset's approval status.

Previews, extracted text, and embeddings are rebuilt asynchronously, so they lag the response by a few minutes.

| Parameter           | Type    | Required | Description                                                                                                                                |
| ------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `mode`              | string  | Yes      | Upload mode: `base64` or `request_upload_url`.                                                                                             |
| `assetId`           | string  | Yes      | ID (UUID) of the existing asset whose file is being replaced.                                                                              |
| `fileBase64`        | string  | No       | Base64-encoded content of the new file version. Required when `mode=base64`.                                                               |
| `filename`          | string  | No       | Filename for the new version, used for the file extension. Does **not** rename the asset. Omit to keep the filename the asset already has. |
| `notifyDownloaders` | boolean | No       | Email everyone who previously downloaded this asset (default `false`).                                                                     |
| `notifySharers`     | boolean | No       | Email everyone who previously shared this asset (default `false`).                                                                         |
| `notifyViewers`     | boolean | No       | Email everyone who previously viewed this asset. This can be a large audience (default `false`).                                           |

The response `status` is one of `replaced`, `upload_url_created`, `rejected`, or `failed`.

**Required scope:** `mcp` + asset access permissions (the caller must have EDIT access to the asset)

### `update_asset`

Partially update an existing asset's metadata. Only the fields you provide change; omitted fields are left untouched. This does **not** replace the asset or re-process its underlying file. The caller must have EDIT access to the asset, otherwise the response returns an error and nothing is changed.

> **Note**
>
> `categoryValueIds` and `collectionIds` **replace** the asset's tag and collection sets when provided — pass the full desired list, not just additions. Omit them to leave tags and collections unchanged.

Sharing and general access are not changed here; use `asset_internal_share` for that.

| Parameter           | Type      | Required | Description                                                                                        |
| ------------------- | --------- | -------- | -------------------------------------------------------------------------------------------------- |
| `assetId`           | string    | Yes      | ID (UUID) of the asset to update.                                                                  |
| `name`              | string    | No       | New display name. Omit to leave unchanged.                                                         |
| `description`       | string    | No       | New description. Pass an empty string to clear it; omit to leave unchanged.                        |
| `categoryValueIds`  | string\[] | No       | Full set of tag (category value) IDs to assign. Replaces existing tags.                            |
| `collectionIds`     | string\[] | No       | Full set of collection IDs the asset should belong to. Replaces existing collections.              |
| `isInternal`        | boolean   | No       | Whether the asset is internal-only. Omit to leave unchanged.                                       |
| `isThirdParty`      | boolean   | No       | Whether the asset is third-party. Omit to leave unchanged.                                         |
| `isDownloadEnabled` | boolean   | No       | Whether downloads are enabled for the asset. Omit to leave unchanged.                              |
| `expirationDate`    | string    | No       | Expiration timestamp as an ISO 8601 instant, e.g. `2026-12-31T00:00:00Z`. Omit to leave unchanged. |

**Required scope:** `mcp` + asset access permissions (the caller must have EDIT access to the asset)

## Sharing tools

These tools modify who can access an asset inside your Masset workspace. (To share content *externally* via a public link, use the content room tools below.)

### `asset_internal_share`

Share one or more assets internally with users, groups, and optionally the whole organization. Named user and group shares **merge** into the existing access list — pass `userShares` / `groupShares`, each with a `shareLevel` of `VIEW` or `EDIT`. Existing higher direct shares are preserved (and surfaced as warnings) rather than lowered. `generalAccessType`, when provided, is a full general-access update: `RESTRICTED` removes organization-wide access, while `ORGANIZATION` grants it at `generalAccessShareLevel`. The caller must be allowed to share every asset; if not, the response returns an error for that asset and no sharing changes are applied. Resolve user and group IDs via `list_users` and `list_groups` when you only have names.

| Parameter                 | Type      | Required | Description                                                                                                   |
| ------------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| `assetIds`                | string\[] | Yes      | Asset IDs (UUIDs) to update (max 100).                                                                        |
| `userShares`              | object\[] | No       | Direct user shares to merge. Each item: `userId` (UUID) and `shareLevel` (`VIEW` or `EDIT`).                  |
| `groupShares`             | object\[] | No       | Group shares to merge. Each item: `groupId` (UUID) and `shareLevel` (`VIEW` or `EDIT`).                       |
| `generalAccessType`       | string    | No       | Full general-access update: `RESTRICTED` or `ORGANIZATION`. Omit to leave organization-wide access unchanged. |
| `generalAccessShareLevel` | string    | No       | Organization share level when `generalAccessType=ORGANIZATION`: `VIEW` or `EDIT` (default `VIEW`).            |

**Required scope:** `mcp` + asset access permissions (the caller must be able to share each target asset)

## Activity tools

These tools provide insight into how assets are being used across your organization.

### `get_asset_activity`

Get usage activity (views, downloads, shares) for specific assets, optionally scoped to specific internal users. Returns per-asset counts including zero-activity assets. Use this after resolving asset IDs from `list_collections` and user IDs from `list_groups`. The `internalUserIds` parameter filters internal user events only — external and content room activity is always included.

| Parameter         | Type      | Required | Description                                                                                                          |
| ----------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `assetIds`        | string\[] | Yes      | Asset IDs (UUIDs) to report on (max 250).                                                                            |
| `internalUserIds` | string\[] | No       | Scope internal events to these user IDs only (max 500). External/content room events are always included unfiltered. |
| `start`           | string    | No       | Start of the analytics window in ISO 8601 format. Omit for all-time.                                                 |
| `end`             | string    | No       | End of the analytics window in ISO 8601 format. Omit for all-time.                                                   |

**Required scope:** `mcp` + analytics permissions

## Discovery tools

These tools help you understand the taxonomy, structure, and organizational context of content in your Masset library.

### `get_search_context`

Retrieve available search taxonomy for the current tenant. Returns categories and tags, plus collections visible to the current user. Use this before `asset_search` when you need to map natural-language terms to tag or collection names.

This tool takes no parameters.

**Required scope:** `mcp`

### `list_collections`

List collections visible to you, with their asset IDs. Use this to resolve a collection name (e.g., "Q1 Launch Materials") into a list of asset IDs that can be passed to `get_asset_activity`. Pass a search term to filter by collection name, or omit to list all visible collections.

| Parameter | Type   | Required | Description                                                                                          |
| --------- | ------ | -------- | ---------------------------------------------------------------------------------------------------- |
| `search`  | string | No       | Filter collections by name (case-insensitive substring match). Omit to list all visible collections. |

**Required scope:** `mcp` + collections permissions

### `list_groups`

List user groups visible to you, with their member user IDs. Use this to resolve a group name (e.g., "Sales") into a list of user IDs that can be passed to `get_asset_activity`. Pass a search term to filter by group name, or omit to list all visible groups.

| Parameter | Type   | Required | Description                                                                                |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------------ |
| `search`  | string | No       | Filter groups by name (case-insensitive substring match). Omit to list all visible groups. |

**Required scope:** `mcp` + groups permissions

### `list_users`

Look up user details by ID, or list all users in the company. Use this to resolve user IDs from `list_groups` into names, or to find users by name or email. Pass `userIds` to look up specific users, or omit to list all users (optionally filtered by search).

| Parameter | Type      | Required | Description                                                                                            |
| --------- | --------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `userIds` | string\[] | No       | Specific user IDs (UUIDs) to look up (max 500). If omitted, lists all company users.                   |
| `search`  | string    | No       | Filter users by name or email (case-insensitive substring match). Only used when `userIds` is omitted. |

**Required scope:** `mcp` + users permissions

### `list_boards`

List boards visible to you, with their names and descriptions. Use this to resolve a board name (e.g., "Q1 Launch Plan") into a `boardId` that can be passed to `content_room_create` or `content_room_update`. Pass a search term to filter by board name, or omit to list all visible boards.

| Parameter | Type   | Required | Description                                                                                |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------------ |
| `search`  | string | No       | Filter boards by name (case-insensitive substring match). Omit to list all visible boards. |

**Required scope:** `mcp` + boards permissions

## Content room tools

These tools find, create, and update content rooms — the multi-asset shares you manage from the **Shares** page in Masset. A content room is a shareable page of assets, boards, and collections, with a page layout and an optional welcome note, and it can be associated with HubSpot CRM objects. Content rooms produce a public URL that can be shared with the recipient.

### `content_room_find`

Find content rooms owned by the current user by ID, CRM reference, or free-text CRM lookup. Provide exactly one of: `contentRoomId`, `crmRef`, or `crmLookup`. `crmLookup` searches synced HubSpot contacts/companies/deals; if it matches multiple objects, the response includes a `candidates` list and no rooms — call again with `crmRef` set to one of the candidates to disambiguate. Use this before `content_room_create` to check whether a room already exists for a given recipient.

| Parameter       | Type   | Required | Description                                                                                                             |
| --------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| `contentRoomId` | string | No       | Specific content room ID (UUID) to fetch.                                                                               |
| `crmRef`        | object | No       | Explicit CRM reference: `crmType=HUBSPOT`, `crmObjectType=CONTACT \| COMPANY \| DEAL`, `crmObjectId`=remote HubSpot ID. |
| `crmLookup`     | string | No       | Free-text CRM lookup (e.g., "John Smith"). Returns rooms associated with the matched HubSpot object.                    |

**Required scope:** `mcp:content_room_read` + content room management permissions

### `content_room_list`

List all content rooms owned by the current user. Each room includes its asset, board, and collection IDs, its layout and welcome note, populated CRM references (with HubSpot display names when available), and a `publicUrl` that can be shared with the recipient. Use `content_room_find` to locate a single room by ID or CRM association rather than listing them all.

This tool takes no parameters.

**Required scope:** `mcp:content_room_read` + content room management permissions

### `content_room_create`

Create a new content room owned by the current user. At least one of `assetIds`, `boardIds`, or `collectionIds` must be supplied. The room shows boards first, then assets, then collections, each in the order given. Boards and collections are included by reference, so later changes to them show up in the room. Anything you can't share is skipped and reported in `warnings`; if nothing is left, no room is created. Optionally set a welcome note and a page layout. A content room may optionally be associated with a CRM object (HubSpot contact, company, or deal). Provide either `crmRef` (an explicit reference) **or** `crmLookup` (a free-text term such as a person's name) — never both. `crmLookup` searches synced HubSpot data; if it matches multiple objects, the response includes a `candidates` list and no room is created. The returned room includes a `publicUrl` that can be shared with the recipient. Use `content_room_find` first to check whether an existing room already serves the same recipient.

| Parameter              | Type      | Required | Description                                                                                 |
| ---------------------- | --------- | -------- | ------------------------------------------------------------------------------------------- |
| `name`                 | string    | No       | Display name for the content room.                                                          |
| `assetIds`             | string\[] | No       | Asset IDs (UUIDs) to associate with the new room.                                           |
| `boardIds`             | string\[] | No       | Board IDs (UUIDs) to associate with the new room.                                           |
| `collectionIds`        | string\[] | No       | Collection IDs (UUIDs) to include in the new room, after its boards and assets.             |
| `note`                 | string    | No       | Welcome note shown to recipients (plain text, up to 2,000 characters).                      |
| `layout`               | string    | No       | Page layout: `SHOWCASE` (default), `LETTER`, `SPOTLIGHT`, `LIBRARY`, `PRESS_KIT`, or `ASK`. |
| `crmRef`               | object    | No       | Explicit CRM reference. Mutually exclusive with `crmLookup`.                                |
| `crmLookup`            | string    | No       | Free-text CRM lookup. Mutually exclusive with `crmRef`.                                     |
| `expiresAt`            | string    | No       | Optional expiration timestamp (ISO 8601) for the public link.                               |
| `notificationsEnabled` | boolean   | No       | Whether owner notifications should fire for this room (default `true`).                     |

**Required scope:** `mcp:content_room_write` + content room management permissions

### `content_room_update`

Update an existing content room owned by the current user. Asset, board, and collection associations **merge**: `addAssetIds`/`addBoardIds`/`addCollectionIds` append to the end of the room (boards, then assets, then collections), and `removeAssetIds`/`removeBoardIds`/`removeCollectionIds` prune from it. Items not mentioned are preserved in their current order. To replace the full set, supply both add and remove lists. A change that would leave the room empty is refused. The welcome note is replaced when you supply `note` (an empty string removes it), and the layout when you supply `layout`; both are otherwise preserved. The CRM association is preserved unless you supply a new `crmRef`/`crmLookup` or set `clearCrm=true`. The expiration is preserved unless you supply a new `expiresAt` or set `clearExpiresAt=true`. Only the original creator of the room may update it.

| Parameter             | Type      | Required | Description                                                                                                         |
| --------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
| `contentRoomId`       | string    | Yes      | ID (UUID) of the content room to update.                                                                            |
| `name`                | string    | No       | New display name for the content room.                                                                              |
| `addAssetIds`         | string\[] | No       | Asset IDs (UUIDs) to add to the room.                                                                               |
| `removeAssetIds`      | string\[] | No       | Asset IDs (UUIDs) to remove from the room.                                                                          |
| `addBoardIds`         | string\[] | No       | Board IDs (UUIDs) to add to the room.                                                                               |
| `removeBoardIds`      | string\[] | No       | Board IDs (UUIDs) to remove from the room.                                                                          |
| `addCollectionIds`    | string\[] | No       | Collection IDs (UUIDs) to add to the end of the room.                                                               |
| `removeCollectionIds` | string\[] | No       | Collection IDs (UUIDs) to remove from the room.                                                                     |
| `note`                | string    | No       | New welcome note (plain text, up to 2,000 characters). An empty string removes the note.                            |
| `layout`              | string    | No       | New page layout: `SHOWCASE`, `LETTER`, `SPOTLIGHT`, `LIBRARY`, `PRESS_KIT`, or `ASK`.                               |
| `crmRef`              | object    | No       | Replacement CRM reference. Mutually exclusive with `crmLookup` and `clearCrm`.                                      |
| `crmLookup`           | string    | No       | Free-text CRM lookup. Mutually exclusive with `crmRef` and `clearCrm`.                                              |
| `clearCrm`            | boolean   | No       | Set `true` to remove any existing CRM association. Mutually exclusive with `crmRef` and `crmLookup`.                |
| `expiresAt`           | string    | No       | New expiration timestamp (ISO 8601). Mutually exclusive with `clearExpiresAt`.                                      |
| `clearExpiresAt`      | boolean   | No       | Set `true` to remove any existing expiration (make the public link permanent). Mutually exclusive with `expiresAt`. |

**Required scope:** `mcp:content_room_write` + content room management permissions

## Content request tools

These tools let AI clients submit content requests on behalf of the current user. Requests become tasks that admins or asset owners can act on within the Masset app.

### `content_request_form_get`

Return the custom fields an admin has configured for new-asset requests. Call this **before** `content_request_create` with `kind="NEW_ASSET"` to learn which questions to ask the user.

Each field has an `id`, `label`, `fieldType` (`MULTIPLE_CHOICE`, `DROPDOWN`, `YES_NO`, `SHORT_TEXT`, or `LONG_TEXT`), a `required` flag, and — for choice fields — the selectable `options`, each with an `id` and `label`.

When fields are returned, collect answers and pass them to `content_request_create` via the `answers` parameter. When no fields are returned, the company has not configured a custom form; submit a free-text request with `fileType` and `message` instead.

This tool takes no parameters.

**Required scope:** `mcp` + asset access permissions

### `content_request_create`

Create a Masset content request that becomes a task tracked in the app, routed to the appropriate Masset owner or team.

For `kind="NEW_ASSET"`, always call `content_request_form_get` first to learn how the company collects new-asset requests. If it returns fields, ask the user those questions and submit the collected answers via `answers`. If it returns no fields, submit a free-text request with `fileType` and `message` instead.

Pass `kind="ASSET_CHANGE"` together with `assetId` and `changeDescription` to ask the asset owner to update an existing asset; the caller must have READ access to the target asset.

| Parameter           | Type      | Required | Description                                                                                                                                                                                       |
| ------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `kind`              | string    | Yes      | Request kind: `NEW_ASSET` or `ASSET_CHANGE`.                                                                                                                                                      |
| `fileType`          | string    | No       | File type for the requested new asset (e.g., `pdf`, `mp4`). Used for `NEW_ASSET` when no custom form is configured.                                                                               |
| `message`           | string    | No       | Free-text message describing the new asset request. Used for `NEW_ASSET` when no custom form is configured.                                                                                       |
| `assetId`           | string    | No       | Existing asset UUID to request a change against. Required when `kind=ASSET_CHANGE`.                                                                                                               |
| `changeDescription` | string    | No       | Free-text description of the requested change. Required when `kind=ASSET_CHANGE`.                                                                                                                 |
| `answers`           | object\[] | No       | Answers to the configured custom form (from `content_request_form_get`). Each answer has `fieldId` plus `optionIds` (choice/dropdown) or `text` (short/long text; `"true"`/`"false"` for yes/no). |
| `matchAcknowledged` | boolean   | No       | Set `true` to proceed with a `NEW_ASSET` request after the user has reviewed a high-confidence existing-asset match (default `false`).                                                            |

The response may come back in one of several states instead of a created task:

* **`requiresConfirmation=true`** — an existing asset may already satisfy the request. Show `matchCandidates` to the user and, only if they still want a new asset, call again with `matchAcknowledged=true`.
* **`disabled=true`** — the company has turned off content requests. No task is created.
* **`externalLink`** — the company routes content requests to an external system. No task is created; hand the URL to the user so they can submit the request there.

**Required scope:** `mcp` + asset access permissions

## Training tools

These tools manage Masset Training — fact-based learning sessions delivered via Slack. The tools cover the full lifecycle: discover sessions, edit DRAFT sessions (sources, facts, questions, manual inputs), AI-generate content, transition through lifecycle states, and read leaderboards and user stats.

> **Note**
>
> Training write tools require the calling user to have EDIT permission on the target training session. Only DRAFT sessions are editable for content mutations; lifecycle transitions are governed by the rules described under `training_session_lifecycle`.

### `training_session_list`

List training sessions in the company. Discovery tool — returns lightweight session metadata suitable for choosing a `trainingSessionId` to pass to `training_session_get`, `training_leaderboard_get`, or any of the training write tools.

| Parameter | Type   | Required | Description                                                                                           |
| --------- | ------ | -------- | ----------------------------------------------------------------------------------------------------- |
| `status`  | string | No       | Optional status filter (case-insensitive): `draft`, `running`, `paused`, `completed`, or `cancelled`. |

**Required scope:** `mcp` + training management permissions

### `training_session_get`

Get a single training session with its full dashboard: session metadata (status, schedule, audience, duration); summary stats (targeted/mastered/participants/non-responders, attempts, average score); per-fact stats (attempts, completions, mastered users, average score); and per-user progress (total points, completed attempts, mastered fact count, last attempt). Set `includeAttempts=true` to also include the attempt timeline (large; default off).

| Parameter           | Type    | Required | Description                                                          |
| ------------------- | ------- | -------- | -------------------------------------------------------------------- |
| `trainingSessionId` | string  | Yes      | Training session ID (UUID).                                          |
| `includeAttempts`   | boolean | No       | Include the full attempt timeline (default `false`; large response). |

**Required scope:** `mcp` + training management permissions (READ on session)

### `training_session_create`

Create a new training session in DRAFT status. Returns the new session detail with the generated `trainingSessionId` — use that ID to attach sources/facts/questions and eventually start the session via `training_session_lifecycle`. Audience: pass `targetUserIds` and/or `targetGroupIds` — at least one is required before the session can start.

| Parameter        | Type      | Required | Description                                                                                                                                                                                   |
| ---------------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`          | string    | Yes      | Display title for the session.                                                                                                                                                                |
| `durationDays`   | integer   | Yes      | Number of days the session runs (1–365).                                                                                                                                                      |
| `description`    | string    | No       | Optional description shown in the editor.                                                                                                                                                     |
| `runOnDays`      | string\[] | No       | Days of the week the session runs. Uppercase weekday names (`MONDAY`..`SUNDAY`). Defaults to `MONDAY`–`FRIDAY`.                                                                               |
| `sendAtTime`     | string    | No       | Local time-of-day to send the question as `HH:mm` at any whole minute, e.g. `09:07`. Interpreted in each recipient's time zone; delivered at or shortly after this time. Defaults to `10:00`. |
| `targetUserIds`  | string\[] | No       | User IDs (UUIDs) to enroll directly.                                                                                                                                                          |
| `targetGroupIds` | string\[] | No       | Group IDs (UUIDs) to enroll (members are expanded at delivery time).                                                                                                                          |

**Required scope:** `mcp` + training management permissions

### `training_session_update`

Update the metadata, schedule, and audience of a DRAFT training session. Sessions in `RUNNING`/`PAUSED`/`COMPLETED`/`CANCELLED` status are **not** editable. Audience replace: `targetUserIds` and `targetGroupIds`, when supplied, fully **replace** the prior audience (not merge). `runOnDays`, when supplied, fully replaces the prior schedule.

| Parameter           | Type      | Required | Description                                                                                                                                     |
| ------------------- | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `trainingSessionId` | string    | Yes      | Training session ID (UUID).                                                                                                                     |
| `title`             | string    | Yes      | Display title for the session.                                                                                                                  |
| `durationDays`      | integer   | Yes      | Number of days the session runs (1–365).                                                                                                        |
| `description`       | string    | No       | Optional description. Omit to preserve the current value; pass an empty string to clear it.                                                     |
| `runOnDays`         | string\[] | No       | Days of the week the session runs (uppercase weekday names).                                                                                    |
| `sendAtTime`        | string    | No       | Local send time as `HH:mm` at any whole minute, e.g. `09:07`, interpreted in each recipient's time zone. Omit to leave the send time unchanged. |
| `targetUserIds`     | string\[] | No       | User IDs (UUIDs). Replaces prior list.                                                                                                          |
| `targetGroupIds`    | string\[] | No       | Group IDs (UUIDs). Replaces prior list.                                                                                                         |

**Required scope:** `mcp` + training management permissions (EDIT on session)

### `training_session_lifecycle`

Transition a training session through its lifecycle. Returns `ok=true` with the new status, or `ok=false` with errors when the transition is illegal.

Valid actions:

* `start`: DRAFT → RUNNING (requires at least 1 active fact, 1 active question, and 1 user/group target)
* `pause`: RUNNING → PAUSED (cancels open attempts)
* `resume`: PAUSED → RUNNING (extends end time by paused duration)
* `complete`: RUNNING/PAUSED → COMPLETED
* `cancel`: any non-COMPLETED → CANCELLED

| Parameter           | Type   | Required | Description                                                            |
| ------------------- | ------ | -------- | ---------------------------------------------------------------------- |
| `trainingSessionId` | string | Yes      | Training session ID (UUID).                                            |
| `action`            | string | Yes      | Lifecycle action: `start`, `pause`, `resume`, `complete`, or `cancel`. |

**Required scope:** `mcp` + training management permissions (EDIT on session)

### `training_sources_manage`

Attach or detach a source (asset, collection, or board) on a DRAFT training session. Sources back the AI fact-generation flow (`training_generate`).

* `attach`: provide exactly **one** of `assetId` / `collectionId` / `boardId`.
* `detach`: provide `sourceId` (the foreign ID of the asset/collection/board to detach — type is auto-resolved).

| Parameter           | Type   | Required | Description                                                      |
| ------------------- | ------ | -------- | ---------------------------------------------------------------- |
| `trainingSessionId` | string | Yes      | Training session ID (UUID).                                      |
| `action`            | string | Yes      | `attach` or `detach`.                                            |
| `assetId`           | string | No       | Asset ID (UUID). Use for `action=attach` with an asset.          |
| `collectionId`      | string | No       | Collection ID (UUID). Use for `action=attach` with a collection. |
| `boardId`           | string | No       | Board ID (UUID). Use for `action=attach` with a board.           |
| `sourceId`          | string | No       | Source foreign ID to detach. Required for `action=detach`.       |

**Required scope:** `mcp` + training management permissions (EDIT on session)

### `training_manual_inputs_manage`

Create, update, or delete a manual input (free-form text the AI uses for fact generation) on a DRAFT training session.

| Parameter           | Type   | Required | Description                                              |
| ------------------- | ------ | -------- | -------------------------------------------------------- |
| `trainingSessionId` | string | Yes      | Training session ID (UUID).                              |
| `action`            | string | Yes      | `create`, `update`, or `delete`.                         |
| `manualInputId`     | string | No       | Manual input ID (UUID). Required for `update`/`delete`.  |
| `contents`          | string | No       | Free-form text contents. Required for `create`/`update`. |

**Required scope:** `mcp` + training management permissions (EDIT on session)

### `training_facts_manage`

Create, update, or delete a fact on a DRAFT training session. Source attribution lists (`sourceAssetIds`, `sourceCollectionIds`, `sourceBoardIds`), when provided on `update`, **replace** the prior values; omit a list to leave it untouched. `delete` is a soft-delete — existing attempts continue to resolve to the fact.

| Parameter               | Type      | Required | Description                                                       |
| ----------------------- | --------- | -------- | ----------------------------------------------------------------- |
| `trainingSessionId`     | string    | Yes      | Training session ID (UUID).                                       |
| `action`                | string    | Yes      | `create`, `update`, or `delete`.                                  |
| `trainingSessionFactId` | string    | No       | Fact ID (UUID). Required for `update`/`delete`.                   |
| `text`                  | string    | No       | Fact text. Required for `create`/`update`.                        |
| `sourceAssetIds`        | string\[] | No       | Source asset IDs to attribute the fact to.                        |
| `sourceCollectionIds`   | string\[] | No       | Source collection IDs.                                            |
| `sourceBoardIds`        | string\[] | No       | Source board IDs.                                                 |
| `origin`                | string    | No       | `MANUAL` (default) or `GENERATED`.                                |
| `isActive`              | boolean   | No       | Whether the fact is active in the question pool (default `true`). |
| `displayOrder`          | integer   | No       | Display order (0-indexed). Optional on update.                    |

**Required scope:** `mcp` + training management permissions (EDIT on session)

### `training_questions_manage`

Create, update, or delete a question on a DRAFT training session. `factIds`, when provided on `update`, **replaces** prior links. Every active question must link to at least one active fact before the session can start.

| Parameter                   | Type      | Required | Description                                               |
| --------------------------- | --------- | -------- | --------------------------------------------------------- |
| `trainingSessionId`         | string    | Yes      | Training session ID (UUID).                               |
| `action`                    | string    | Yes      | `create`, `update`, or `delete`.                          |
| `trainingSessionQuestionId` | string    | No       | Question ID (UUID). Required for `update`/`delete`.       |
| `text`                      | string    | No       | Question text. Required for `create`/`update`.            |
| `factIds`                   | string\[] | No       | Fact IDs (UUIDs) the question covers (active facts only). |
| `origin`                    | string    | No       | `MANUAL` (default) or `GENERATED`.                        |
| `isActive`                  | boolean   | No       | Whether the question is active (default `true`).          |
| `displayOrder`              | integer   | No       | Display order. Optional on update.                        |

**Required scope:** `mcp` + training management permissions (EDIT on session)

### `training_generate`

AI-generate facts or questions on a DRAFT training session.

* `facts_from_source`: generates facts from one source (asset/collection/board) attached to the session. Requires `sourceId`. Idempotent — re-runs add new attribution rather than duplicate facts.
* `questions_from_facts`: generates questions from the session's facts. Optional `sourceIds` to bias generation toward specific sources.

| Parameter           | Type      | Required | Description                                         |
| ------------------- | --------- | -------- | --------------------------------------------------- |
| `trainingSessionId` | string    | Yes      | Training session ID (UUID).                         |
| `action`            | string    | Yes      | `facts_from_source` or `questions_from_facts`.      |
| `sourceId`          | string    | No       | Source ID (UUID). Required for `facts_from_source`. |
| `sourceIds`         | string\[] | No       | Optional source IDs to bias question generation.    |
| `maxFacts`          | integer   | No       | Max facts to request (1–100, default 12).           |
| `maxQuestions`      | integer   | No       | Max questions to request (1–100, default 12).       |

**Required scope:** `mcp` + training management permissions (EDIT on session)

### `training_leaderboard_get`

Get the company-wide or session-specific training leaderboard. Each entry includes `rank`, `userId`, `displayName`, `email`, `totalPoints`, and `currentStreak`.

* `scope=company` (default): top entries across all sessions, with optional caller-context window when the caller sits outside the top.
* `scope=session`: top entries within a single training session — `trainingSessionId` is required.

| Parameter            | Type    | Required | Description                                                          |
| -------------------- | ------- | -------- | -------------------------------------------------------------------- |
| `scope`              | string  | No       | `company` (default) or `session`.                                    |
| `trainingSessionId`  | string  | No       | Training session ID (UUID). Required when `scope=session`.           |
| `limit`              | integer | No       | Maximum number of top entries (default 10, max 100).                 |
| `includeUserContext` | boolean | No       | Include caller context window when `scope=company` (default `true`). |

**Required scope:** `mcp` + training management permissions (READ on session when `scope=session`)

### `training_user_stats_get`

Per-user training stats across all sessions in the company. Use this to answer "who is most engaged?", "who has the longest streak?", or "what's user X's rank?". Returns for each user: `currentStreak`, `longestStreak`, `totalPoints`, `leaderboardRank`, `totalParticipants`, `masteredFactCount` (cross-session), `participatingSessionCount`, and `lastActivityAt`. Resolve user IDs first via `list_users` / `list_groups` when you only have names.

| Parameter | Type      | Required | Description                                   |
| --------- | --------- | -------- | --------------------------------------------- |
| `userIds` | string\[] | Yes      | User IDs (UUID strings) to look up (max 100). |

**Required scope:** `mcp` + training management permissions