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

# MCP tools reference

> Tool names, parameters, response shapes, and call examples for the Metal MCP server.

This page documents the tools exposed by the Metal MCP server at `https://mcp.metal.ai/mcp`. Your AI client discovers these tools automatically after OAuth sign-in. Use this reference when building integrations, debugging tool calls, or understanding what data comes back.

<Info>
  Tool availability depends on your OAuth scopes and organization settings. If a tool is missing or returns `insufficient scope`, your connection may not have been granted that permission.
</Info>

## How tool calls work

Metal implements the [Model Context Protocol](https://modelcontextprotocol.io) over streamable HTTP. Your client sends JSON-RPC messages to `/mcp`; each **tools/call** request names a tool and passes a JSON **arguments** object.

When you inspect a call in a client like Cursor, you typically see:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "name": "search_companies",
  "arguments": {
    "query": "Acme Industrial",
    "pageSize": 5
  }
}
```

### Response format

Every tool returns a **text content** block containing JSON (or a plain-text error message). Successful responses fall into three shapes:

**Single record** — the JSON object is the payload directly:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "507f1f77bcf86cd799439011",
  "canonicalName": "Acme Industrial",
  "sector": "Industrials"
}
```

**Paginated list** — results are wrapped in `data` and `pagination`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "canonicalName": "Acme Industrial"
    }
  ],
  "pagination": {
    "paginationMode": "page",
    "page": 1,
    "limit": 20,
    "resultCount": 1,
    "totalCount": 47,
    "totalPages": 3,
    "hasMore": true
  }
}
```

**Document search** — `data` contains grouped documents and excerpts instead of a flat array:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "documents": [
      {
        "document": {
          "id": "507f1f77bcf86cd799439011",
          "displayName": "Acme CIM 2024",
          "sourceLinkMarkdown": "[Acme CIM 2024 p. 12](https://app.metal.ai/entities/507f1f77bcf86cd799439011)"
        },
        "excerpts": [
          {
            "page": 12,
            "text": "Revenue grew 18% year-over-year...",
            "relevance": 0.92,
            "sourceLinkMarkdown": "[Acme CIM 2024 p. 12](https://app.metal.ai/entities/507f1f77bcf86cd799439011)"
          }
        ]
      }
    ],
    "citationGuidance": "Always include each excerpt's sourceLinkMarkdown when presenting facts from search_documents."
  },
  "pagination": {
    "paginationMode": "page",
    "page": 1,
    "limit": 20,
    "resultCount": 3,
    "documentCount": 1,
    "hasMore": false
  }
}
```

### Errors

When a call fails validation or the backend returns an error, the tool result is marked as an error and the text content holds a message:

```
query is required for search_companies; use list_companies for filter-only browsing
```

Common error patterns:

| Message                                       | Cause                                                             |
| --------------------------------------------- | ----------------------------------------------------------------- |
| `insufficient scope: requires read:companies` | OAuth token lacks the scope for that tool                         |
| `unauthenticated request`                     | Session expired or connection not signed in                       |
| `Rate limit exceeded`                         | Per-user rate limit hit; JSON body includes `retry_after` seconds |

Rate-limit errors return structured JSON in the error text:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": "Rate limit exceeded",
  "limit": 60,
  "remaining": 0,
  "retry_after": 42
}
```

### Pagination

Most list and search tools use **page mode** (`paginationMode: "page"`). Pass `page` (default `1`) and `pageSize` (default `20`, max `50`). Continue while `hasMore` is `true`.

`get_list_entries` uses **cursor mode** (`paginationMode: "cursor"`). Pass `nextToken` from the prior response to fetch the next page.

Field definitions for each resource type are available as MCP resources — see [Resources](#resources) below.

### OAuth scopes

Tools require OAuth scopes granted during sign-in:

| Scope                 | Tools                                                                    |
| --------------------- | ------------------------------------------------------------------------ |
| `read:companies`      | `list_companies`, `search_companies`, `list_company_tags`, `get_company` |
| `read:documents`      | `get_document`, `search_documents`                                       |
| `read:people`         | `search_people`, `get_person`                                            |
| `read:deals`          | `search_deals`, `get_deal`                                               |
| `read:users`          | `search_users`, `get_current_user`, `get_user`                           |
| `read:teams`          | `list_teams`, `get_team`                                                 |
| `read:lists`          | `list_lists`, `get_list`, `get_list_entries`                             |
| `read:activities`     | `get_activities`, `get_activity`                                         |
| `read:workflows`      | Workflow read and inspect tools                                          |
| `read:screenings`     | `search_screenings`, `get_screening`, `get_screening_scores`             |
| `read:scores`         | `list_scoring_frameworks`, `get_scoring_framework`                       |
| `write:workflow_runs` | `run_workflow`, `review_workflow_hitl_step`                              |
| `write:workflows`     | Workflow authoring tools                                                 |

***

## Companies

### `search_companies`

Search companies by name. Uses hybrid semantic + keyword matching on company names.

**Scope:** `read:companies`

| Parameter                  | Type      | Required | Description                                        |
| -------------------------- | --------- | -------- | -------------------------------------------------- |
| `query`                    | string    | Yes      | Company name or alias to search                    |
| `sector`                   | string    | No       | Filter by sector                                   |
| `subsector`                | string    | No       | Filter by subsector                                |
| `tagIds`                   | string\[] | No       | Company tag IDs (resolve with `list_company_tags`) |
| `assigneeIds`              | string\[] | No       | Metal user IDs assigned to the company             |
| `assignedToMe`             | boolean   | No       | Restrict to companies assigned to you              |
| `assignedTeamIds`          | string\[] | No       | Team IDs (resolve with `list_teams`)               |
| `assignedTeamStatuses`     | string\[] | No       | Team coverage labels (e.g. Mine/Learn, Monitor)    |
| `city`, `state`, `country` | string    | No       | Location filters                                   |
| `page`, `pageSize`         | integer   | No       | Pagination                                         |

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "name": "search_companies",
  "arguments": {
    "query": "Acme",
    "sector": "Industrials",
    "pageSize": 5
  }
}
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "canonicalName": "Acme Industrial",
      "sector": "Industrials",
      "subsector": "Industrial Automation",
      "shortDescription": "Provider of factory automation systems."
    }
  ],
  "pagination": {
    "paginationMode": "page",
    "page": 1,
    "limit": 5,
    "resultCount": 1,
    "hasMore": false
  }
}
```

### `list_companies`

Browse companies with structured filters only — no text query. Use this for sector, tag, team, or location lists.

**Scope:** `read:companies`

Same filter parameters as `search_companies` except **`query` is not accepted**. At least one filter is required.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "name": "list_companies",
  "arguments": {
    "sector": "Healthcare",
    "assignedToMe": true,
    "pageSize": 20
  }
}
```

### `list_company_tags`

List company tags so you can pass exact IDs to `tagIds` filters.

**Scope:** `read:companies`

| Parameter          | Type    | Description         |
| ------------------ | ------- | ------------------- |
| `page`, `pageSize` | integer | Optional pagination |

Returns a paginated list of tag objects with `id` and `name`.

### `get_company`

Get a full company profile by ID.

**Scope:** `read:companies`

| Parameter | Type   | Required                        |
| --------- | ------ | ------------------------------- |
| `id`      | string | Yes — 24-character hex ObjectID |

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "name": "get_company",
  "arguments": {
    "id": "507f1f77bcf86cd799439011"
  }
}
```

Returns an enriched company record including `enrichedValues` with citations. Field keys match the `metal://fields/companies` resource.

***

## Documents

### `search_documents`

Search document content or list documents by type and date.

**Scope:** `read:documents`

| Parameter          | Type      | Description                                            |
| ------------------ | --------- | ------------------------------------------------------ |
| `query`            | string    | Content search text. Pass `""` for filter-only listing |
| `documentType`     | string    | Filter by type (see `metal://document-types`)          |
| `companyIds`       | string\[] | Restrict to documents linked to these companies        |
| `documentIds`      | string\[] | Restrict to specific document IDs                      |
| `sort`             | string    | `latest` or `oldest` — used when `query` is empty      |
| `page`, `pageSize` | integer   | Pagination over matching excerpts                      |

**Content search** — find text inside documents:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "name": "search_documents",
  "arguments": {
    "query": "unit economics SaaS",
    "pageSize": 10
  }
}
```

**Filter-only listing** — recent CIMs without relevance ranking:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "name": "search_documents",
  "arguments": {
    "query": "",
    "documentType": "CIM (Confidential Information Memorandum)",
    "sort": "latest",
    "pageSize": 10
  }
}
```

Always cite `sourceLinkMarkdown` from each excerpt when presenting facts.

### `get_document`

Get extracted text from a document by line number.

**Scope:** `read:documents`

| Parameter   | Type    | Description                                             |
| ----------- | ------- | ------------------------------------------------------- |
| `id`        | string  | Document ID (required)                                  |
| `startLine` | integer | First line to return (default `1`)                      |
| `endLine`   | integer | Last line (default start + 499; max 500 lines per call) |

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "name": "get_document",
  "arguments": {
    "id": "507f1f77bcf86cd799439011",
    "startLine": 1
  }
}
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "document": {
    "id": "507f1f77bcf86cd799439011",
    "displayName": "Acme CIM 2024",
    "documentType": "CIM (Confidential Information Memorandum)",
    "sourceLinkMarkdown": "[Acme CIM 2024](https://app.metal.ai/entities/507f1f77bcf86cd799439011)"
  },
  "content": "     1|Executive Summary\n     2|Acme Industrial is a leading...",
  "lines": [
    { "line": 1, "text": "Executive Summary", "page": 1 },
    { "line": 2, "text": "Acme Industrial is a leading...", "page": 1 }
  ],
  "startLine": 1,
  "endLine": 500,
  "returnedLines": 2,
  "reachedEof": true,
  "status": "EOF - End of document",
  "citationGuidance": "When presenting information from this document, include the source markdown link from document.sourceLinkMarkdown."
}
```

When `reachedEof` is `false`, call again with `startLine` set to `nextLine`.

***

## People

### `search_people`

Search contacts by name, title, company, or email.

**Scope:** `read:people`

| Parameter          | Type      | Description                                                             |
| ------------------ | --------- | ----------------------------------------------------------------------- |
| `query`            | string    | Search text                                                             |
| `assigneeIds`      | string\[] | Filter by assigned Metal user IDs                                       |
| `assignedToMe`     | boolean   | Contacts assigned to you                                                |
| `contactType`      | string    | Advisor, Banker, Board, Executive, Investor, Lender, Operational, Other |
| `priority`         | integer   | 1 (highest) through 5 (lowest)                                          |
| `page`, `pageSize` | integer   | Pagination                                                              |

### `get_person`

Get a full contact profile by ID.

**Scope:** `read:people`

| Parameter | Type   | Required |
| --------- | ------ | -------- |
| `id`      | string | Yes      |

***

## Deals

### `search_deals`

Search or filter deals. `query` is optional for filter-only searches.

**Scope:** `read:deals`

| Parameter                       | Type      | Description                             |
| ------------------------------- | --------- | --------------------------------------- |
| `query`                         | string    | Deal name, company, or description text |
| `companyIds`                    | string\[] | Target company IDs                      |
| `sourceCompanyIds`              | string\[] | Sourcing bank or advisor company IDs    |
| `ownerUserIds`                  | string\[] | Deal owner user IDs                     |
| `ownerTeamIds`                  | string\[] | Deal owner team IDs                     |
| `status`, `stage`               | string    | Internal enum or org CRM label          |
| `createdAfter`, `createdBefore` | string    | RFC3339 timestamps                      |
| `updatedAfter`, `updatedBefore` | string    | RFC3339 timestamps                      |
| `closeAfter`, `closeBefore`     | string    | RFC3339 timestamps                      |
| `page`, `pageSize`              | integer   | Pagination                              |

Resolve company names with `search_companies`, user names with `search_users`, and team IDs with `list_teams` before passing ID filters.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "name": "search_deals",
  "arguments": {
    "companyIds": ["507f1f77bcf86cd799439011"],
    "status": "Active",
    "pageSize": 10
  }
}
```

### `get_deal`

Get a full deal record by ID.

**Scope:** `read:deals`

| Parameter | Type   | Required |
| --------- | ------ | -------- |
| `id`      | string | Yes      |

***

## Users and teams

### `get_current_user`

Return the authenticated user and connected organization. No arguments.

**Scope:** `read:users`

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "user": {
    "id": "507f1f77bcf86cd799439011",
    "email": "you@firm.com",
    "firstName": "Alex",
    "lastName": "Smith"
  },
  "org": {
    "id": "507f1f77bcf86cd799439012",
    "name": "Example Capital",
    "displayName": "Example Capital Partners"
  }
}
```

### `search_users`

Search Metal users by name or email. **`query` is required.**

**Scope:** `read:users`

### `get_user`

Get a user by ID.

**Scope:** `read:users`

| Parameter | Type   | Required |
| --------- | ------ | -------- |
| `id`      | string | Yes      |

### `list_teams`

List teams in your organization. Returns team names and IDs for use in deal and company filters.

**Scope:** `read:teams`

### `get_team`

Get a team by ID.

**Scope:** `read:teams`

| Parameter | Type   | Required |
| --------- | ------ | -------- |
| `id`      | string | Yes      |

***

## Lists

### `list_lists`

List resource lists in your organization.

**Scope:** `read:lists`

| Parameter          | Type    | Description                                        |
| ------------------ | ------- | -------------------------------------------------- |
| `resourceType`     | string  | Optional filter: `company`, `person`, `deal`, etc. |
| `page`, `pageSize` | integer | Pagination                                         |

### `get_list`

Get a list's metadata and column schema by ID. Does not include row data — use `get_list_entries`.

**Scope:** `read:lists`

| Parameter | Type   | Required |
| --------- | ------ | -------- |
| `id`      | string | Yes      |

### `get_list_entries`

Page through list rows with cursor pagination.

**Scope:** `read:lists`

| Parameter   | Type    | Description                        |
| ----------- | ------- | ---------------------------------- |
| `id`        | string  | List ID (required)                 |
| `pageSize`  | integer | Rows per page (default 50, max 50) |
| `nextToken` | string  | Token from prior response          |

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": [
    {
      "id": "entry-id",
      "resourceId": "507f1f77bcf86cd799439011",
      "values": { "Priority": "High" }
    }
  ],
  "pagination": {
    "paginationMode": "cursor",
    "limit": 50,
    "resultCount": 1,
    "hasMore": true,
    "nextToken": "eyJwYWdlIjoyfQ=="
  }
}
```

***

## Activities

### `get_activities`

Get meetings, calls, and interactions for a company.

**Scope:** `read:activities`

| Parameter          | Type    | Required | Description |
| ------------------ | ------- | -------- | ----------- |
| `participantId`    | string  | Yes      | Company ID  |
| `page`, `pageSize` | integer | No       | Pagination  |

### `get_activity`

Get a single activity by ID, including participants, linked deals, and attached documents.

**Scope:** `read:activities`

| Parameter | Type   | Required |
| --------- | ------ | -------- |
| `id`      | string | Yes      |

***

## Screenings and scoring

### `search_screenings`

List or filter CIM screenings. Free-text `query` is not supported — use structured filters.

**Scope:** `read:screenings`

| Parameter                                | Type      | Description                                                  |
| ---------------------------------------- | --------- | ------------------------------------------------------------ |
| `companyIds`, `dealIds`, `dataEntityIds` | string\[] | Link filters                                                 |
| `status`, `statuses`                     | string    | Screening status                                             |
| `sector`, `subsector`, `industry`        | string    | Taxonomy filters                                             |
| `createdAfter`, `createdBefore`          | string    | RFC3339                                                      |
| `updatedAfter`, `updatedBefore`          | string    | RFC3339                                                      |
| `sortBy`                                 | string    | `createdAt`, `updatedAt`, `companyName`, `revenue`, `ebitda` |
| `sortOrder`                              | string    | `asc` or `desc`                                              |
| `page`, `pageSize`                       | integer   | Pagination                                                   |

### `get_screening`

Get a screening by ID, including financials, analysis, and validation metadata.

**Scope:** `read:screenings`

| Parameter | Type   | Required |
| --------- | ------ | -------- |
| `id`      | string | Yes      |

### `get_screening_scores`

Get score records for a screening.

**Scope:** `read:screenings` and `read:scores`

| Parameter     | Type   | Description                       |
| ------------- | ------ | --------------------------------- |
| `screeningId` | string | Required                          |
| `framework`   | string | Optional filter by framework name |

### `list_scoring_frameworks`

List scoring frameworks visible to your organization.

**Scope:** `read:scores`

| Parameter         | Type    | Description                                 |
| ----------------- | ------- | ------------------------------------------- |
| `entityType`      | string  | `company`, `person`, `deal`, or `screening` |
| `includeStandard` | boolean | Append standard frameworks                  |
| `onlyStandard`    | boolean | Return only standard frameworks             |

### `get_scoring_framework`

Get a framework definition by ID. Standard frameworks use IDs like `standard:Porter's Five Forces`.

**Scope:** `read:scores`

| Parameter | Type   | Required |
| --------- | ------ | -------- |
| `id`      | string | Yes      |

***

## Workflows

Workflow tools split into **read/inspect**, **run**, and **authoring** groups.

### Read and inspect

**Scope:** `read:workflows`

| Tool                    | Purpose                                                                                |
| ----------------------- | -------------------------------------------------------------------------------------- |
| `list_workflows`        | Discover workflow IDs (`page`, `pageSize`)                                             |
| `get_workflow`          | Workflow definition overview (`workflowId`, optional `version`, `fieldPath`)           |
| `get_workflow_step`     | Full step definition (`workflowId`, `stepId`, optional `childStepId`, `version`)       |
| `list_workflow_runs`    | Find runs (`resourceType`, `resourceId`, `statuses`, date filters, pagination)         |
| `get_workflow_run`      | Run status and outputs (`workflowRunId`, `view` or `fieldPath`)                        |
| `get_workflow_run_step` | Step evidence (`workflowRunId`, `stepId`, optional `itemIndex`, `childStepId`, `view`) |

`view` shortcuts for `get_workflow_run`: `overview`, `steps`, `outputs`, `errors`, `failures`, `artifacts`, `citations`, `full`. Do not pass `view` and `fieldPath` together.

`view` shortcuts for `get_workflow_run_step`: `overview`, `outputs`, `transcript`, `toolCalls`, `artifacts`, `errors`, `iteratorItems`, `hitl`, `execution`, `full`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "name": "get_workflow",
  "arguments": {
    "workflowId": "507f1f77bcf86cd799439011",
    "fieldPath": "inputSchema"
  }
}
```

### Run workflows

**Scope:** `write:workflow_runs`

#### `run_workflow`

Start a workflow run. Inspect `inputSchema` with `get_workflow` first and supply every required field in `input`.

| Parameter    | Type   | Required | Description                            |
| ------------ | ------ | -------- | -------------------------------------- |
| `workflowId` | string | Yes      | 24-character hex ID                    |
| `input`      | object | No       | Workflow inputs matching `inputSchema` |
| `visibility` | string | No       | Run visibility override                |

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "name": "run_workflow",
  "arguments": {
    "workflowId": "507f1f77bcf86cd799439011",
    "input": {
      "companyId": "507f1f77bcf86cd799439012"
    }
  }
}
```

The response includes immediate run status and polling guidance. Call `get_workflow_run` when the run completes to read bounded outputs.

#### `review_workflow_hitl_step`

Approve or reject a human-in-the-loop step. Inspect the pending step with `get_workflow_run_step` using `view: "hitl"` first.

| Parameter         | Type      | Required | Description                                         |
| ----------------- | --------- | -------- | --------------------------------------------------- |
| `workflowRunId`   | string    | Yes      | Run ID                                              |
| `stepId`          | string    | Yes      | HITL step ID                                        |
| `action`          | string    | Yes      | `approve` or `reject`                               |
| `approvedItemIds` | string\[] | No       | Required item IDs when approving structured reviews |

### Authoring

**Scope:** `write:workflows`

These tools create and edit draft workflows:

| Tool                              | Purpose                                                    |
| --------------------------------- | ---------------------------------------------------------- |
| `create_workflow`                 | Create a new draft workflow                                |
| `update_workflow_details`         | Update name, description, and metadata                     |
| `configure_workflow_input`        | Set input schema and UI schema                             |
| `configure_workflow_trigger`      | Configure how the workflow starts                          |
| `configure_workflow_output`       | Configure output sections                                  |
| `add_workflow_step`               | Add a step to the definition                               |
| `update_workflow_step`            | Update an existing step                                    |
| `delete_workflow_step`            | Remove a step                                              |
| `move_workflow_step`              | Reorder steps                                              |
| `list_workflow_authoring_options` | List valid step types, triggers, and configuration options |

Call `list_workflow_authoring_options` before authoring to discover allowed step types and field shapes. Authoring tool inputs are validated server-side; validation errors return structured JSON in the error text.

***

## Resources

Your client can read MCP **resources** alongside tools. These are read-only catalogs — not tool calls.

| URI                         | Description                                        |
| --------------------------- | -------------------------------------------------- |
| `metal://document-types`    | Valid `documentType` values for `search_documents` |
| `metal://resource-types`    | Entity types, associated tools, and relationships  |
| `metal://fields/companies`  | Field keys returned by company tools               |
| `metal://fields/people`     | Field keys returned by people tools                |
| `metal://fields/deals`      | Field keys returned by deal tools                  |
| `metal://fields/documents`  | Field keys returned by document tools              |
| `metal://fields/activities` | Field keys returned by activity tools              |

## Prompts

The server also exposes guided **prompts** your client can invoke:

| Prompt                  | Arguments                                |
| ----------------------- | ---------------------------------------- |
| `company_due_diligence` | `company_name` (required), `focus_areas` |
| `deal_analysis`         | `deal_name` (required)                   |
| `sector_landscape`      | `sector` (required), `region`            |
| `document_research`     | `topic` (required), `document_type`      |
| `contact_network`       | `company_name` (required), `role_filter` |

Prompts orchestrate multiple tool calls — they do not return data directly.

***

## Tool index

<AccordionGroup>
  <Accordion title="All 43 tools (alphabetical)">
    `add_workflow_step` · `configure_workflow_input` · `configure_workflow_output` · `configure_workflow_trigger` · `create_workflow` · `delete_workflow_step` · `get_activities` · `get_activity` · `get_company` · `get_current_user` · `get_deal` · `get_document` · `get_list` · `get_list_entries` · `get_person` · `get_scoring_framework` · `get_screening` · `get_screening_scores` · `get_team` · `get_user` · `get_workflow` · `get_workflow_run` · `get_workflow_run_step` · `get_workflow_step` · `list_companies` · `list_company_tags` · `list_lists` · `list_scoring_frameworks` · `list_teams` · `list_workflow_authoring_options` · `list_workflow_runs` · `list_workflows` · `move_workflow_step` · `review_workflow_hitl_step` · `run_workflow` · `search_companies` · `search_deals` · `search_documents` · `search_people` · `search_screenings` · `search_users` · `update_workflow_details` · `update_workflow_step`
  </Accordion>
</AccordionGroup>