MCP tools reference - Metal Docs

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.

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.

How tool calls work

Metal implements the Model Context Protocol over streamable HTTP. Your client sends JSON-RPC messages to /mcp; each tools/call request names a tool and passes a JSON arguments object.

Tool discovery and schemas

After OAuth sign-in, your MCP client discovers the exact live tool metadata from the server with the MCP tools/list method. That response is the source of truth for each tool’s description, inputSchema, and safety annotations. Use this page as the human-readable reference for tool behavior, common parameters, scopes, response shapes, and examples. If you are generating code, validating arguments, or debugging a client integration, inspect the live inputSchema from tools/list instead of hardcoding this page’s parameter tables. When you inspect a call in a client like Cursor, you typically see:

{
  "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:

{
  "id": "507f1f77bcf86cd799439011",
  "canonicalName": "Acme Industrial",
  "sector": "Industrials"
}

Paginated list — results are wrapped in data and pagination:

{
  "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:

{
  "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:

{
  "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 below.

OAuth scopes

Tools require OAuth scopes granted during sign-in:

Scope	Tools
`read:companies`	`list_companies`, `search_companies`, `list_company_tags`, `get_companies`, `get_company`, `get_custom_field_definitions` for company fields
`read:documents`	`get_document`, `search_documents`
`read:people`	`search_people`, `list_person_tags`, `get_person`
`read:deals`	`search_deals`, `get_deal`, `get_custom_field_definitions` for deal fields
`read:users`	`search_users`, `get_current_user`, `get_user`
`read:teams`	`list_teams`, `get_team`
`read:lists`	`list_lists`, `get_list`, `get_list_entries`
`write:lists`	`create_list`, `update_list`, `update_list_columns`, `add_list_entries`, `update_list_entry` (paired with `read:lists`)
`read:dashboards`	Dashboard read tools; also grants access to `list_sdk_methods` and `get_sdk_method`
`write:dashboards`	`create_dashboard`, `update_dashboard`, `add_dashboard_widget`, `update_dashboard_widget`, `reorder_dashboard_widgets`, `remove_dashboard_widget`, `get_dashboard_widget_source` (paired with `read:dashboards`)
`read:programmatic`	`list_sdk_methods`, `get_sdk_method`
`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`)
`customFilters`	object[]	No	Org-defined custom company field filters (discover with `get_custom_field_definitions`)
`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

{
  "name": "search_companies",
  "arguments": {
    "query": "Acme",
    "sector": "Industrials",
    "pageSize": 5
  }
}

{
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "canonicalName": "Acme Industrial",
      "website": "https://acme.example",
      "linkedinUrl": "https://www.linkedin.com/company/acme-industrial",
      "sector": "Industrials",
      "subsector": "Industrial Automation",
      "shortDescription": "Provider of factory automation systems."
    }
  ],
  "pagination": {
    "paginationMode": "page",
    "page": 1,
    "limit": 5,
    "resultCount": 1,
    "hasMore": false
  }
}

website and linkedinUrl use the resolved observation value when available, with the native company field as a fallback. The remaining discovery fields keep their compact search representation.

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

{
  "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. Default returns all tags; explicit `pageSize` is capped at 50

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

`get_companies`

Retrieve selected resolved fields for exact company IDs. Use this when you already have IDs and need the same fields across many companies without loading each full profile. Find IDs with search_companies or list_companies. Compact discovery results already return resolved website and linkedinUrl. Use get_company only when you need the full profile, including enrichedValues. Scope: read:companies

Parameter	Type	Required	Description
`ids`	string[]	Yes	1 to 500 unique 24-character company ObjectIDs
`fields`	string[]	Yes	1 to 100 unique selectable field names
`includeProvenance`	boolean	No	Include compact source metadata for each value. Defaults to `false`

id and canonicalName are always returned and must not appear in fields. relevance is returned only by search_companies and cannot be requested here. A request can contain at most 2,500 ID-field cells. For example, 500 IDs can request up to five fields. The server rejects responses above 512 KiB. Reduce the IDs or fields and retry when a response exceeds that limit. Observation-backed fields such as website and linkedinUrl use the resolved observation value when available, with the native company field as a fallback. That is the compact equivalent of the values on a full get_company profile. Use the metal://fields/companies MCP resource to discover standard selectable fields. It includes public native company fields (except relevance) and registered company observation fields. Use get_custom_field_definitions for organization-defined fields:

Request schema custom fields as custom.<key>, such as custom.ideaPriorityStr.
Request custom financial metrics with their existing custom:<key> names, such as custom:arr.
Do not request the complete custom, enrichedValues, or metricCustom maps.

{
  "name": "get_companies",
  "arguments": {
    "ids": [
      "665f1c2a9b1e4a0012a3b4c5"
    ],
    "fields": [
      "website",
      "linkedinUrl",
      "sector",
      "custom.ideaPriorityStr"
    ],
    "includeProvenance": false
  }
}

{
  "companies": [
    {
      "id": "665f1c2a9b1e4a0012a3b4c5",
      "canonicalName": "Acme Industrials",
      "values": {
        "website": "https://acme.example",
        "linkedinUrl": null,
        "sector": "Industrials",
        "custom.ideaPriorityStr": "High"
      }
    }
  ],
  "missingIds": [],
  "resultCount": 1
}

Companies stay in requested ID order. Every requested field appears in values; absent or unresolved values are null. Nonexistent or inaccessible records appear in missingIds without failing records that were found. When includeProvenance is true, each company also has a provenance map parallel to values. Observation provenance can include provider, source, sourceId, capturedOn, resolution, and compact citations with id, title, type, and sourceUrl. Native and custom fallbacks identify their sourceKind. Citation excerpts and source text are not returned.

`get_company`

Get a full company profile by ID. Scope: read:companies

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

{
  "name": "get_company",
  "arguments": {
    "id": "507f1f77bcf86cd799439011"
  }
}

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

Custom fields

`get_custom_field_definitions`

List org-defined custom field definitions for companies and deals. Use this before passing customFilters to search_companies, list_companies, or search_deals, and before requesting organization-defined fields with get_companies. Scope: read:companies for company fields; read:deals for deal fields.

Parameter	Type	Description
`resourceTypes`	string[]	Optional resource types to return: `companies`, `deals`. Defaults to every supported resource type your token can read.

Each definition includes the field key, display name, type, whether it can be used in customFilters, and supported operators. String fields support eq, neq, in, and nin; number fields support eq, neq, gt, gte, lt, lte, in, and nin; boolean fields support eq and neq; date fields support range operators gt, gte, lt, and lte.

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:

{
  "name": "search_documents",
  "arguments": {
    "query": "unit economics SaaS",
    "pageSize": 10
  }
}

Filter-only listing — recent CIMs without relevance ranking:

{
  "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)

{
  "name": "get_document",
  "arguments": {
    "id": "507f1f77bcf86cd799439011",
    "startLine": 1
  }
}

{
  "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, Vendor, Other
`tagIds`	string[]	Person tag IDs (resolve with `list_person_tags`)
`priority`	integer	1 (highest) through 5 (lowest)
`page`, `pageSize`	integer	Pagination

`list_person_tags`

List person tags so you can pass exact IDs to the tagIds filter on search_people. Scope: read:people

Parameter	Type	Description
`page`, `pageSize`	integer	Optional. Default returns all tags; explicit `pageSize` is capped at 50

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

`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
`customFilters`	object[]	Org-defined custom deal field filters (discover with `get_custom_field_definitions`)
`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.

{
  "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

{
  "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

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

List authoring

The list write tools let an assistant build and maintain resource lists from a chat surface — create a list, evolve its columns, add rows, and edit cells. Every write requires both read:lists and write:lists, so tokens without the read scope cannot write either.

write:lists must be registered in PropelAuth for your organization before the OAuth authorize step will accept it. If the connection completes but every list write returns insufficient scope: requires write:lists, ask an org admin to add the scope. See the overview callout.

`create_list`

Create a new resource list. The list is created private to you regardless of your role; sharing is managed in the Metal UI. Scope: read:lists and write:lists

Parameter	Type	Required	Description
`name`	string	Yes	List name
`resourceType`	string	Yes	One of `company`, `person`, `deal`, `dataEntity`, `activity`, `screening`, `limitedPartner`, `fundraisingProcess`, or `none` for a custom list whose rows are not tied to any Metal resource
`description`	string	No	Optional description
`columns`	object[]	No	Initial columns — each `{ name, type }`. Column `type` must be `string`, `number`, or `boolean`; other column types (date, currency, enrichment, reference, scoring) are managed in the UI

{
  "name": "create_list",
  "arguments": {
    "name": "Q4 industrials pipeline",
    "resourceType": "deal",
    "description": "Tracking industrials deals for Q4 review",
    "columns": [
      { "name": "Priority", "type": "string" },
      { "name": "Revenue estimate", "type": "number" }
    ]
  }
}

Returns the created list including each column’s server-assigned ID. Save those IDs to pass to update_list_columns, add_list_entries, and update_list_entry.

`update_list`

Rename a list or change its description. Only provided fields are patched. Scope: read:lists and write:lists

Parameter	Type	Required	Description
`id`	string	Yes	List ID
`name`	string	No	New name
`description`	string	No	New description. Pass an empty string to clear

At least one of name or description is required. Use update_list_columns to change the column schema.

`update_list_columns`

Modify a list’s column schema by adding, removing, or renaming columns. Scope: read:lists and write:lists

Parameter	Type	Required	Description
`id`	string	Yes	List ID
`add`	object[]	No	Columns to append. Each `{ name, type }` with `type` one of `string`, `number`, `boolean`
`remove`	string[]	No	Column IDs to delete. Removing a column also deletes its values on every entry
`rename`	object[]	No	Column renames. Each `{ columnId, name }`

At least one of add, remove, or rename is required. Column IDs come from get_list.

Removing a column is destructive — it deletes the column and its cell values on every entry. There is no soft-delete. Adding or editing columns can also trigger background enrichment or computation jobs for existing entries.

Renames run before adds and removes, so a rename that targets a missing column fails before any destructive delete commits. Removing and renaming the same column ID in a single call is rejected up front.

`add_list_entries`

Append rows to a list in one batch (backend cap: 1,000 entries per call). Scope: read:lists and write:lists

Parameter	Type	Required	Description
`id`	string	Yes	List ID
`entries`	object[]	Yes	Entries to add

Each entry supports:

Field	Type	Description
`resourceId`	string	Metal resource ID to link this row to. Resolve with the `search_*` tools first
`resourceType`	string	Reference type: `company`, `person`, `deal`, `dataEntity`, `activity`, `screening`, `limitedPartner`, or `fundraisingProcess`
`values`	object	Cell values keyed by column ID (from `get_list`). Types are inferred from the JSON: string, number, boolean, or null

resourceId and resourceType are provided together to link an entry to an existing Metal record, or both omitted for a standalone row (required for resourceType=none lists). dataEntity lists always require a resource.

{
  "name": "add_list_entries",
  "arguments": {
    "id": "507f1f77bcf86cd799439011",
    "entries": [
      {
        "resourceId": "507f1f77bcf86cd799439012",
        "resourceType": "deal",
        "values": {
          "60c...priority": "High",
          "60c...revenue": 42000000
        }
      }
    ]
  }
}

The endpoint returns partial success — inspect the failed array in the response. Each failed item includes the input index and error message. Do not assume every entry landed.

`update_list_entry`

Update cell values on one existing list entry. Scope: read:lists and write:lists

Parameter	Type	Required	Description
`listId`	string	Yes	List ID
`entryId`	string	Yes	Entry ID (from `get_list_entries`)
`values`	object	Yes	Cell values keyed by column ID. Types are inferred (string, number, boolean, null)

Updating a cell that maps to a source resource writes back to that deal, company, or person in the CRM. This mutates data outside the list. Confirm intent before calling.

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

Dashboards

Dashboard authoring tools let an assistant build canvas dashboards end to end: create the dashboard, add widgets with agent, script, or resource-list backing, rearrange the layout, and edit widget authoring source in place. Only canvas dashboards are supported; other dashboard contexts return no access. Every write requires both read:dashboards and write:dashboards. Layout writes use optimistic concurrency: each write echoes the baseVersion from the caller’s most recent read, and a stale token returns 409 Conflict without persisting. On 409, re-fetch the dashboard and retry with the fresh version.

write:dashboards must be registered in PropelAuth for your organization before the OAuth authorize step will accept it. If the connection completes but every dashboard write returns insufficient scope: requires write:dashboards, ask an org admin to add the scope. See the overview callout.

`create_dashboard`

Create an empty canvas dashboard. Org-scoped and private to you until shared in the UI. Scope: read:dashboards and write:dashboards

Parameter	Type	Required	Description
`name`	string	Yes	Dashboard name
`description`	string	No	Optional description

Returns the new dashboardId. Add widgets with add_dashboard_widget.

`update_dashboard`

Rename or re-describe a canvas dashboard. Sparse patch — omitted fields are unchanged; an empty string clears a field. Layout is never touched by this tool. Scope: read:dashboards and write:dashboards

Parameter	Type	Required	Description
`dashboardId`	string	Yes	Dashboard ID
`name`	string	No	New name
`description`	string	No	New description; `""` clears

`add_dashboard_widget`

Add one widget to a canvas dashboard. Scope: read:dashboards and write:dashboards

Parameter	Type	Required	Description
`dashboardId`	string	Yes	Dashboard ID
`title`	string	Yes	Widget title
`widgetType`	string	Yes	One of `TABLE`, `BAR_CHART`, `LINE_CHART`, `PIE_CHART`, `COMPOSED_CHART`, `LIST`, `HTML`
`dataSource`	string	Yes	`agent`, `script`, or `resourceList` (see below)
`prompt`	string	Conditional	Required when `dataSource` is `agent`
`script`	string	Conditional	Required when `dataSource` is `script`. A Python `DASHBOARD_DATA` script; preview-validated before persisting
`widgetCode`	string	No	HTML template for agent-backed `HTML` widgets only
`resourceListId`	string	Conditional	Required when `dataSource` is `resourceList`. `LIST` widgets only. Format-validated only — list existence and permissions are checked at render time, not save time
`col`, `row`	integer	No	Zero-based grid coordinates. `row` defaults to the next free row
`width`, `height`	integer	No	Cell counts. Default `6x4`; `12x6` for `LIST` widgets

Data source rules:

agent — supply prompt. The widget renders through Metal’s agent runtime.
script — supply script (Python DASHBOARD_DATA). Rejected if empty or whitespace-only; enforced against a per-script byte cap. Not allowed on LIST widgets.
resourceList — supply resourceListId. Only valid for LIST widgets; LIST widgets require this data source.

Script authors: use list_sdk_methods and get_sdk_method to look up SDK signatures before writing widget scripts.

{
  "name": "add_dashboard_widget",
  "arguments": {
    "dashboardId": "507f1f77bcf86cd799439011",
    "title": "Deals by stage",
    "widgetType": "BAR_CHART",
    "dataSource": "agent",
    "prompt": "Group open deals by stage and show counts."
  }
}

Returns the created widget and the full updated layout.

`update_dashboard_widget`

Sparse patch for one widget. Omitted fields are unchanged. widgetType cannot be changed — remove and re-add. Scope: read:dashboards and write:dashboards

Parameter	Type	Required	Description
`dashboardId`	string	Yes	Dashboard ID
`widgetId`	string	Yes	Widget ID (from `get_dashboard` or the add response)
`title`	string	No	New title
`prompt`	string	No	New prompt (agent-backed widgets). Mutually exclusive with `script`
`script`	string	No	New Python script (script-backed widgets). Preview-validated before persisting. Mutually exclusive with `prompt`
`widgetCode`	string	No	New HTML template (agent-backed `HTML` widgets only)
`col`, `row`, `width`, `height`	integer	No	New grid geometry

Read the current script or template with get_dashboard_widget_source before rewriting.

`reorder_dashboard_widgets`

Reposition existing widgets. Widgets not listed keep their current geometry. Scope: read:dashboards and write:dashboards

Parameter	Type	Required	Description
`dashboardId`	string	Yes	Dashboard ID
`order`	object[]	Yes	Widgets to move. Each `{ widgetId, col, row, width?, height? }`

`remove_dashboard_widget`

Remove one widget from a canvas dashboard. Scope: read:dashboards and write:dashboards

Parameter	Type	Required
`dashboardId`	string	Yes
`widgetId`	string	Yes

Removing a default or system widget is durable — the server records a tombstone so the widget is not reinserted on the next dashboard reconcile.

`get_dashboard_widget_source`

Read the current authoring source of a widget on a canvas dashboard: the Python script (with sha256 and byte count) for script-backed widgets, or the stored HTML template (widgetCode) for agent-backed HTML widgets. Use this before editing so you push a change against the exact source the server holds. Scope: read:dashboards and write:dashboards (source is an authoring asset and is gated by edit access to the dashboard, not view access)

Parameter	Type	Required
`dashboardId`	string	Yes
`widgetId`	string	Yes

{
  "dashboardId": "507f1f77bcf86cd799439011",
  "widgetId": "507f1f77bcf86cd799439099",
  "script": "def run(ctx):\n    ...",
  "scriptSha256": "9f8...",
  "scriptByteCount": 412
}

widgetCode is empty until an agent-backed HTML widget has rendered its first template.

SDK methods

The Metal SDK method catalog lets scripts discover the read-only Python methods available to run_metal_sdk_query and to dashboard widget DASHBOARD_DATA scripts. Look up methods before writing code so signatures and response shapes are confirmed rather than guessed. Both tools are on the core MCP surface and accept either scope: Scope: read:programmatic or read:dashboards

`list_sdk_methods`

Search available SDK methods by name, HTTP path, or documentation text.

Parameter	Type	Description
`query`	string	Optional substring filter
`page`, `pageSize`	integer	Pagination

`get_sdk_method`

Get the exact signature, route, response contract, examples, and usage notes for one method returned by list_sdk_methods.

Parameter	Type	Required
`name`	string	Yes

Call get_sdk_method before using an SDK call in a script — its examples pin down the shape you need to return from a widget’s DASHBOARD_DATA output.

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.

{
  "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

{
  "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_building_options`	List valid step types, triggers, and configuration options

Call list_workflow_building_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`	Company fields. Standard keys selectable with `get_companies` exclude `relevance`, which is search-only.
`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

All 58 tools (alphabetical)

add_dashboard_widget · add_list_entries · add_workflow_step · configure_workflow_input · configure_workflow_output · configure_workflow_trigger · create_dashboard · create_list · create_workflow · delete_workflow_step · get_activities · get_activity · get_company · get_current_user · get_custom_field_definitions · get_dashboard_widget_source · get_deal · get_document · get_list · get_list_entries · get_person · get_scoring_framework · get_screening · get_screening_scores · get_sdk_method · 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_sdk_methods · list_teams · list_workflow_building_options · list_workflow_runs · list_workflows · move_workflow_step · remove_dashboard_widget · reorder_dashboard_widgets · review_workflow_hitl_step · run_workflow · search_companies · search_deals · search_documents · search_people · search_screenings · search_users · update_dashboard · update_dashboard_widget · update_list · update_list_columns · update_list_entry · update_workflow_details · update_workflow_step

​How tool calls work

​Tool discovery and schemas

​Response format

​Errors

​Pagination

​OAuth scopes

​Companies

​search_companies

​list_companies

​list_company_tags

​get_companies

​get_company

​Custom fields

​get_custom_field_definitions

​Documents

​search_documents

​get_document

​People

​search_people

​list_person_tags

​get_person

​Deals

​search_deals

​get_deal

​Users and teams

​get_current_user

​search_users

​get_user

​list_teams

​get_team

​Lists

​list_lists

​get_list

​get_list_entries

​List authoring

​create_list

​update_list

​update_list_columns

​add_list_entries

​update_list_entry

​Activities

​get_activities

​get_activity

​Screenings and scoring

​search_screenings

​get_screening

​get_screening_scores

​list_scoring_frameworks

​get_scoring_framework

​Dashboards

​create_dashboard

​update_dashboard

​add_dashboard_widget

​update_dashboard_widget

​reorder_dashboard_widgets

​remove_dashboard_widget

​get_dashboard_widget_source

​SDK methods

​list_sdk_methods

​get_sdk_method

​Workflows

​Read and inspect

​Run workflows

​run_workflow

​review_workflow_hitl_step

​Authoring

​Resources

​Prompts

​Tool index

How tool calls work

Tool discovery and schemas

Response format

Errors

Pagination

OAuth scopes

Companies

`search_companies`

`list_companies`

`list_company_tags`

`get_companies`

`get_company`

Custom fields

`get_custom_field_definitions`

Documents

`search_documents`

`get_document`

People

`search_people`

`list_person_tags`

`get_person`

Deals

`search_deals`

`get_deal`

Users and teams

`get_current_user`

`search_users`

`get_user`

`list_teams`

`get_team`

Lists

`list_lists`

`get_list`

`get_list_entries`

List authoring

`create_list`

`update_list`

`update_list_columns`

`add_list_entries`

`update_list_entry`

Activities

`get_activities`

`get_activity`

Screenings and scoring

`search_screenings`

`get_screening`

`get_screening_scores`

`list_scoring_frameworks`

`get_scoring_framework`

Dashboards

`create_dashboard`

`update_dashboard`

`add_dashboard_widget`

`update_dashboard_widget`

`reorder_dashboard_widgets`

`remove_dashboard_widget`

`get_dashboard_widget_source`

SDK methods

`list_sdk_methods`

`get_sdk_method`

Workflows

Read and inspect

Run workflows

`run_workflow`

`review_workflow_hitl_step`

Authoring

Resources

Prompts

Tool index