> ## Documentation Index
> Fetch the complete documentation index at: https://docs.royaltyport.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools

> Detailed reference for all tools available on the Royaltyport MCP server.

The Royaltyport MCP server provides tools that let AI assistants browse projects, manage catalog data, upload files, and query financial analytics.

***

## Project Tools

### list\_projects

List all projects for the authenticated organization. The organization is resolved automatically from your authentication token.

**Sample prompt:** "Show me all my projects"

### get\_project

Get a project by ID.

| Parameter   | Type | Required | Default | Description |
| ----------- | ---- | -------- | ------- | ----------- |
| `projectId` | UUID | Yes      | -       | Project ID  |

**Sample prompt:** "Get details about project a1b2c3d4-..."

### search\_project

Search across all resources in a project — contracts, entities, artists, writers, recordings, and compositions.

| Parameter   | Type   | Required | Default | Description                     |
| ----------- | ------ | -------- | ------- | ------------------------------- |
| `projectId` | UUID   | Yes      | -       | Project ID                      |
| `query`     | string | Yes      | -       | Search query (1–500 characters) |

**Sample prompt:** "Search for Sony in my project"

***

## Contract Tools

### list\_contracts

List contracts for a project. Use `includes` to embed extracted sub-resource data inline.

| Parameter   | Type      | Required | Default | Description              |
| ----------- | --------- | -------- | ------- | ------------------------ |
| `projectId` | UUID      | Yes      | -       | Project ID               |
| `page`      | integer   | No       | `1`     | Page number              |
| `perPage`   | integer   | No       | `20`    | Items per page (1–100)   |
| `includes`  | string\[] | No       | -       | Sub-resources to include |

**Valid includes:** `entities`, `artists`, `writers`, `royalties`, `splits`, `costs`, `compensations`, `dates`, `accounting-periods`, `types`, `signatures`, `control-areas`, `creative-approvals`, `balances`, `recordings`, `compositions`

**Sample prompt:** "List all contracts with their royalty terms"

### get\_contract

Get a contract by ID with optional sub-resource includes.

| Parameter    | Type      | Required | Default | Description                                   |
| ------------ | --------- | -------- | ------- | --------------------------------------------- |
| `contractId` | string    | Yes      | -       | Contract ID                                   |
| `projectId`  | UUID      | Yes      | -       | Project ID                                    |
| `includes`   | string\[] | No       | -       | Sub-resources to include (same list as above) |

**Sample prompt:** "Get contract abc-123 with entities and dates"

***

## Entity Tools

### list\_entities

List root entities for a project — companies, labels, publishers, or other organizations.

| Parameter       | Type    | Required | Default | Description                            |
| --------------- | ------- | -------- | ------- | -------------------------------------- |
| `projectId`     | UUID    | Yes      | -       | Project ID                             |
| `page`          | integer | No       | `1`     | Page number                            |
| `perPage`       | integer | No       | `20`    | Items per page (1–100)                 |
| `includeMerged` | boolean | No       | `false` | Include merged (deduplicated) entities |

**Sample prompt:** "List all entities in my project"

### get\_entity

Get an entity by ID with associated artists, writers, and relations.

| Parameter       | Type    | Required | Default | Description             |
| --------------- | ------- | -------- | ------- | ----------------------- |
| `entityId`      | string  | Yes      | -       | Entity ID               |
| `projectId`     | UUID    | Yes      | -       | Project ID              |
| `includeMerged` | boolean | No       | `false` | Include merged entities |

**Sample prompt:** "Get entity ent-456 with merged duplicates"

***

## Artist Tools

### list\_artists

List root artists for a project — performers linked to recordings.

| Parameter       | Type    | Required | Default | Description            |
| --------------- | ------- | -------- | ------- | ---------------------- |
| `projectId`     | UUID    | Yes      | -       | Project ID             |
| `page`          | integer | No       | `1`     | Page number            |
| `perPage`       | integer | No       | `20`    | Items per page (1–100) |
| `includeMerged` | boolean | No       | `false` | Include merged artists |

**Sample prompt:** "Show me all artists in the project"

### get\_artist

Get an artist by ID.

| Parameter       | Type    | Required | Default | Description            |
| --------------- | ------- | -------- | ------- | ---------------------- |
| `artistId`      | string  | Yes      | -       | Artist ID              |
| `projectId`     | UUID    | Yes      | -       | Project ID             |
| `includeMerged` | boolean | No       | `false` | Include merged artists |

**Sample prompt:** "Get details for artist art-789"

***

## Writer Tools

### list\_writers

List root writers for a project — songwriters and composers.

| Parameter       | Type    | Required | Default | Description            |
| --------------- | ------- | -------- | ------- | ---------------------- |
| `projectId`     | UUID    | Yes      | -       | Project ID             |
| `page`          | integer | No       | `1`     | Page number            |
| `perPage`       | integer | No       | `20`    | Items per page (1–100) |
| `includeMerged` | boolean | No       | `false` | Include merged writers |

**Sample prompt:** "List all writers in the project"

### get\_writer

Get a writer by ID.

| Parameter       | Type    | Required | Default | Description            |
| --------------- | ------- | -------- | ------- | ---------------------- |
| `writerId`      | string  | Yes      | -       | Writer ID              |
| `projectId`     | UUID    | Yes      | -       | Project ID             |
| `includeMerged` | boolean | No       | `false` | Include merged writers |

**Sample prompt:** "Get writer wrt-321"

***

## Relation Tools

### list\_relations

List root relations for a project — contacts and people such as managers, A\&R, and lawyers.

| Parameter       | Type    | Required | Default | Description              |
| --------------- | ------- | -------- | ------- | ------------------------ |
| `projectId`     | UUID    | Yes      | -       | Project ID               |
| `page`          | integer | No       | `1`     | Page number              |
| `perPage`       | integer | No       | `20`    | Items per page (1–100)   |
| `includeMerged` | boolean | No       | `false` | Include merged relations |

**Sample prompt:** "Show all contacts in the project"

### get\_relation

Get a relation by ID.

| Parameter       | Type    | Required | Default | Description              |
| --------------- | ------- | -------- | ------- | ------------------------ |
| `relationId`    | string  | Yes      | -       | Relation ID              |
| `projectId`     | UUID    | Yes      | -       | Project ID               |
| `includeMerged` | boolean | No       | `false` | Include merged relations |

**Sample prompt:** "Get relation rel-654"

***

## Recording Tools

### list\_recordings

List recordings for a project — audio tracks identified by ISRC codes.

| Parameter         | Type    | Required | Default | Description                                                  |
| ----------------- | ------- | -------- | ------- | ------------------------------------------------------------ |
| `projectId`       | UUID    | Yes      | -       | Project ID                                                   |
| `page`            | integer | No       | `1`     | Page number                                                  |
| `perPage`         | integer | No       | `20`    | Items per page (1–100)                                       |
| `includeProducts` | boolean | No       | `false` | Include associated products (albums, singles) with UPC codes |

**Sample prompt:** "List recordings with their albums"

### get\_recording

Get a recording by ID with ISRC and artists.

| Parameter         | Type    | Required | Default | Description                 |
| ----------------- | ------- | -------- | ------- | --------------------------- |
| `recordingId`     | string  | Yes      | -       | Recording ID                |
| `projectId`       | UUID    | Yes      | -       | Project ID                  |
| `includeProducts` | boolean | No       | `false` | Include associated products |

**Sample prompt:** "Get recording rec-111 with products"

***

## Composition Tools

### list\_compositions

List compositions for a project — musical works identified by ISWC codes.

| Parameter         | Type    | Required | Default | Description                 |
| ----------------- | ------- | -------- | ------- | --------------------------- |
| `projectId`       | UUID    | Yes      | -       | Project ID                  |
| `page`            | integer | No       | `1`     | Page number                 |
| `perPage`         | integer | No       | `20`    | Items per page (1–100)      |
| `includeProducts` | boolean | No       | `false` | Include associated products |

**Sample prompt:** "List all compositions in my project"

### get\_composition

Get a composition by ID with ISWC and linked writers.

| Parameter         | Type    | Required | Default | Description                 |
| ----------------- | ------- | -------- | ------- | --------------------------- |
| `compositionId`   | string  | Yes      | -       | Composition ID              |
| `projectId`       | UUID    | Yes      | -       | Project ID                  |
| `includeProducts` | boolean | No       | `false` | Include associated products |

**Sample prompt:** "Get composition comp-222"

***

## Statement Tools

### list\_statements

List statements for a project — royalty or revenue reports uploaded as files.

| Parameter   | Type    | Required | Default | Description            |
| ----------- | ------- | -------- | ------- | ---------------------- |
| `projectId` | UUID    | Yes      | -       | Project ID             |
| `page`      | integer | No       | `1`     | Page number            |
| `perPage`   | integer | No       | `20`    | Items per page (1–100) |

**Sample prompt:** "Show all statements in the project"

<Tip>
  For querying the actual revenue data within statements, use the `query` tool with SQL instead.
</Tip>

### get\_statement

Get a statement by ID with processing status and currency.

| Parameter     | Type   | Required | Default | Description  |
| ------------- | ------ | -------- | ------- | ------------ |
| `statementId` | string | Yes      | -       | Statement ID |
| `projectId`   | UUID   | Yes      | -       | Project ID   |

**Sample prompt:** "Get statement 1234"

***

## Upload Tools

### upload\_file

Create a staging record and return a signed upload URL. Upload the file via HTTP PUT to the returned `uploadUrl`. After the upload completes, you **must** call `upload_completed` to trigger processing.

| Parameter      | Type      | Required | Default           | Description                                     |
| -------------- | --------- | -------- | ----------------- | ----------------------------------------------- |
| `projectId`    | UUID      | Yes      | -                 | Project ID                                      |
| `resourceType` | string    | Yes      | -                 | `contract` or `statement`                       |
| `fileName`     | string    | Yes      | -                 | Original file name (e.g. `contract.pdf`)        |
| `fileType`     | string    | No       | `application/pdf` | MIME type of the file                           |
| `fileSize`     | integer   | Yes      | -                 | File size in bytes                              |
| `extractions`  | string\[] | No       | -                 | Extractions to run after upload (contract only) |

**Valid extractions:** `entities`, `artists`, `writers`, `royalties`, `splits`, `costs`, `compensations`, `dates`, `accounting-periods`, `types`, `signatures`, `control-areas`, `creative-approvals`, `balances`, `recordings`, `compositions`

**Sample prompt:** "Upload contract.pdf and extract royalties and dates"

### upload\_completed

Signal that a file upload is complete. Call this after successfully uploading the file via HTTP PUT to the `uploadUrl` returned by `upload_file`. This triggers processing.

| Parameter      | Type   | Required | Default | Description                            |
| -------------- | ------ | -------- | ------- | -------------------------------------- |
| `stagingId`    | string | Yes      | -       | Staging ID returned from `upload_file` |
| `projectId`    | UUID   | Yes      | -       | Project ID                             |
| `resourceType` | string | Yes      | -       | `contract` or `statement`              |

**Sample prompt:** "Signal that upload stg-456 is complete"

### upload\_status

Check the processing status of an uploaded contract or statement.

| Parameter      | Type   | Required | Default | Description                            |
| -------------- | ------ | -------- | ------- | -------------------------------------- |
| `stagingId`    | string | Yes      | -       | Staging ID returned from `upload_file` |
| `projectId`    | UUID   | Yes      | -       | Project ID                             |
| `resourceType` | string | Yes      | -       | `contract` or `statement`              |

**Sample prompt:** "Check the status of upload stg-456"

***

## Download Tools

### download\_file

Get a signed download URL for a contract or statement file. The URL expires in 1 hour.

| Parameter      | Type   | Required | Default | Description                 |
| -------------- | ------ | -------- | ------- | --------------------------- |
| `resourceId`   | string | Yes      | -       | Contract ID or Statement ID |
| `projectId`    | UUID   | Yes      | -       | Project ID                  |
| `resourceType` | string | Yes      | -       | `contract` or `statement`   |

**Sample prompt:** "Download contract abc-123"

***

## Dataroom Tools

### list\_tables

Lists available Dataroom tables and their schemas. Returns a compact summary by default. Set `verbose` to `true` to include full column details (name, data type, description).

| Parameter  | Type      | Required | Default                                        | Description                                            |
| ---------- | --------- | -------- | ---------------------------------------------- | ------------------------------------------------------ |
| `datasets` | string\[] | No       | `["rp_data_external", "rp_data_intermediate"]` | Filter by dataset name                                 |
| `verbose`  | boolean   | No       | `false`                                        | When `true`, includes column details (name, data type) |

**Available datasets:** `rp_data_external`, `rp_data_intermediate`

**Sample prompt:** "What tables are available for querying?"

### query

Execute a read-only SQL query against the Dataroom. Use this for financial analytics — revenue breakdowns, cost reports, statement-level data, and period comparisons.

| Parameter   | Type    | Required           | Default       | Description                                                                                            |
| ----------- | ------- | ------------------ | ------------- | ------------------------------------------------------------------------------------------------------ |
| `sql`       | string  | Yes                | -             | SQL query with `@project_id` named parameter                                                           |
| `projectId` | UUID    | External auth only | Auto-injected | Project ID (required for external auth, auto-injected for internal)                                    |
| `offset`    | integer | No                 | `0`           | Number of rows to skip. Use with truncated results to paginate (e.g., `offset=1000` for the next page) |

Results are capped at 1,000 rows. If the query returns more, `truncated` will be `true` in the response. Use `offset` to paginate through large result sets.

**Sample prompt:** "What are the top 10 recordings by revenue?"