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 result contains at least one content block. Most calls return a text content block containing JSON; get_document_page is the exception, returning a text block with a caption and citation link plus an image block with the rendered page. Failures return a text block with 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": 100,
  "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). When a tool uses a different default or maximum, its parameter row says so — list_tasks and search_tasks default pageSize to 25 and cap it at 100. Continue while hasMore is true. get_list_entries and get_score_history use cursor pagination. For get_list_entries, the cursor is pagination.nextToken; for get_score_history, it is metadata.nextToken. Pass the token 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`, `search_company_taxonomy`, `list_company_tags`, `get_companies`, `get_company`, `get_custom_field_definitions` for company fields
`read:documents`	`search_documents`, `list_documents`, `get_document`, `get_document_types`, `get_document_page`
`read:people`	`search_people`, `list_person_tags`, `get_person`, `get_person_context`
`read:deals`	`search_deals`, `get_deal`, `get_deal_status_and_stages`, `get_custom_field_definitions` for deal fields
`write:deals`	`update_deal_status_and_stage` (paired with `read:deals`)
`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`	`list_dashboards`, `get_dashboard`, `get_dashboard_widget`; 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`, `refresh_dashboard_widget` (paired with `read:dashboards`)
`read:programmatic`	`run_metal_sdk_query`, `list_sdk_methods`, `get_sdk_method`
`read:activities`	`get_activities`, `get_activity`, `get_person_context`
`read:tasks`	`list_tasks`, `search_tasks`, `get_task`
`write:tasks`	`update_task`, `delete_task` (paired with `read:tasks`)
`read:workflows`	Workflow read and inspect tools
`read:screenings`	`search_screenings`, `get_screening`, `get_screening_scores`
`read:scores`	`list_scoring_frameworks`, `get_scoring_framework`, `get_current_scores`, `get_score_history`
`read:funds`	`search_funds`, `get_fund`, `list_fund_tags`
`read:limited_partners`	`search_limited_partners`, `get_limited_partner`, `list_limited_partner_tags`
`read:fundraising_processes`	`search_fundraising_processes`, `get_fundraising_process`, `get_fundraising_status_and_stages`, `list_fundraising_process_tags`
`write:workflow_runs`	`run_workflow`, `review_workflow_hitl_step`, `rerun_workflow_run_from_step`, `publish_pending_workflow_score`, `dismiss_pending_workflow_score`
`write:workflows`	Workflow authoring tools

Companies

Company records returned by search_companies, list_companies, get_company, and get_companies include fileCount, the number of linked documents the caller can see for that company. It appears only when the connection has the read:documents scope; an absent fileCount means the count is unknown — no document read access or a failed lookup. When fileCount is nonzero, pass the company’s ID as companyIds to search_documents or list_documents to work with those documents.

`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, type, and value, plus color and externalReference when set. Match the label against value and pass the tag’s id to tagIds.

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

`search_company_taxonomy`

Search the organization’s canonical industry → sector → subsector hierarchy by a classification term. Returns matching nodes with their IDs, names, and ancestors. Use this before list_companies or search_companies when a request describes a market, vertical, or theme without naming a company, then pass the selected industryId, sectorId, or subsectorId downstream. Scope: read:companies

Parameter	Type	Required	Description
`query`	string	Yes	Classification term such as a market, vertical, or theme
`includeSubsectors`	boolean	No	Also expand each matched sector’s subsectors

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
`rankProfile`	string	`hybrid_rank` (default semantic plus keyword relevance), `hybrid_rank_recency` (adds a freshness bias), or `bm25` (lexical-only keyword ranking without embeddings). `bm25` requires a non-empty `query`
`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
  }
}

Lexical-only search: use rankProfile: "bm25" to match exact terms, names, or phrases. Start with the default hybrid ranking. Retry once with bm25 if hybrid results miss the evidence you need.

{
  "name": "search_documents",
  "arguments": {
    "query": "Northwind earn-out",
    "rankProfile": "bm25",
    "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.

Tool	Purpose
`list_documents`	Inventory document metadata with structured filters, without relevance ranking
`get_document_types`	List built-in and org-custom document types for `documentType` filters
`get_document_page`	Render one physical PDF page as an image when extracted text is not enough

`get_document_page`

Render one physical page of a PDF document as an image. Use it when extracted text from get_document or search_documents loses chart values, layout, units, or table relationships. The tool returns the page image itself, not OCR text or a download link. Scope: read:documents

Parameter	Type	Required	Description
`id`	string	Yes	Document ID from `search_documents` or another document tool
`page`	integer	Yes	Physical PDF page number, starting at `1` (maximum `10000`). This is the page’s position in the file, not its printed page label

{
  "name": "get_document_page",
  "arguments": {
    "id": "507f1f77bcf86cd799439011",
    "page": 14
  }
}

The response contains two content blocks: a text block that names the document and page and includes a source link to cite, and an image block with the rendered page. Request targeted pages rather than the whole document. If rendering fails, the tool returns an error message with retry guidance; the renderer’s HTTP status is not exposed. Match the start of the message to decide what to do:

Error message	What to do
Invalid document ID or page number.	Check the requested input
Invalid document/page or unsupported PDF rendition or size.	Check the page number; otherwise use extracted text instead of retrying the same request
Document page is missing or inaccessible.	Don’t retry this document
Page renderer is busy or rate-limited.	Wait before retrying the same document and page
Page rendering is unavailable or disabled.	Use extracted text; don’t repeatedly retry this tool
Page rendering failed upstream.	Retry the same document and page at most once, then use extracted text and report that the image is unavailable

When the renderer reports a retry delay, the message appends Retry after <delay>.

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, type, and value, plus color and externalReference when set. Match the label against value and pass the tag’s id to tagIds.

`get_person`

Get a full contact profile by ID. Scope: read:people

Parameter	Type	Required
`id`	string	Yes

`get_person_context`

Get the aggregated context for a person: their activities and notes. Scope: read:people and read:activities

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

`get_deal_status_and_stages`

Return the organization’s configured deal statuses and stages as customer-facing labels, plus each label’s internal enum mapping. No arguments. Call this before filtering deals by status or stage, and before update_deal_status_and_stage, so you pass a valid configured label rather than guessing. Scope: read:deals

Field	Description
`statuses`, `stages`	Configured labels, active first
`statusMapping`, `stageMapping`	Label to internal enum value
`ambiguousStatusLabels`, `ambiguousStageLabels`	Labels that map to multiple internal values and cannot be used for updates

`update_deal_status_and_stage`

Move an existing deal to a different pipeline stage and/or status by deal ID. At least one of stage or status is required; values can be the org’s configured labels or Metal’s internal enums. If only one is supplied, the backend keeps the other when the pair stays consistent and otherwise fills a compatible default; an inconsistent pair (for example, a passed status with a non-passed stage) is rejected. Returns the updated deal. This is the only direct deal write tool; there is no MCP create-deal or arbitrary field editor. Scope: read:deals and write:deals

Parameter	Type	Required	Description
`id`	string	Yes	24-character hex deal ID from `search_deals` or `get_deal`
`stage`	string	No	Configured stage label or internal enum value
`status`	string	No	Configured status label or internal enum value

{
  "name": "update_deal_status_and_stage",
  "arguments": {
    "id": "507f1f77bcf86cd799439011",
    "stage": "Sourcing"
  }
}

Investor relations

Read-only tools for your firm’s limited partners (LPs), funds, and fundraising processes. A fundraising process is one LP’s participation in one fund’s raise. Each record type has its own scope: read:limited_partners, read:funds, and read:fundraising_processes. For all three search tools, query is optional. Omit it for filter-only searches instead of passing "*". Date range filters take RFC3339 timestamps. Results use offset pagination (page, pageSize, hasMore).

`search_limited_partners`

Search your firm’s own LP records by name or location text. These are Metal records, not third-party data. Scope: read:limited_partners

Parameter	Type	Description
`query`	string	Name or location text
`type`	string	Investor type. The tool’s input schema lists the accepted enum values
`city`	string	Exact city, such as `Dallas`
`state`	string	Two-letter state or province code, such as `TX`
`country`	string	Full country name, such as `United States`
`companyIds`	string[]	Linked company IDs
`personIds`	string[]	People who are a primary or consultant contact on the LP (resolve with `search_people`)
`tagIds`	string[]	LP tag IDs (resolve with `list_limited_partner_tags`)
`createdAfter`, `createdBefore`	string	RFC3339 timestamps
`updatedAfter`, `updatedBefore`	string	RFC3339 timestamps
`lastActivityAfter`, `lastActivityBefore`	string	RFC3339 timestamps
`page`, `pageSize`	integer	Pagination

{
  "name": "search_limited_partners",
  "arguments": {
    "state": "TX",
    "country": "United States",
    "pageSize": 20
  }
}

`get_limited_partner`

Get a full LP record by ID, including investor type, location, linked company, contacts, AUM, preferred check size, strategy and geography preferences, tags, notes, next steps, and custom fields. Scope: read:limited_partners

Parameter	Type	Required
`id`	string	Yes

`list_limited_partner_tags`

List LP tags so you can pass exact IDs to the tagIds filter on search_limited_partners. Scope: read:limited_partners

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, type, and value, plus color and externalReference when set. Match the label against value and pass the tag’s id to tagIds.

`search_funds`

Search the funds your firm is raising or managing by name or strategy text. Scope: read:funds

Parameter	Type	Description
`query`	string	Name or strategy text
`status`	string	`raising`, `active`, or `closed`
`tagIds`	string[]	Fund tag IDs (resolve with `list_fund_tags`)
`createdAfter`, `createdBefore`	string	RFC3339 timestamps
`updatedAfter`, `updatedBefore`	string	RFC3339 timestamps
`page`, `pageSize`	integer	Pagination

`get_fund`

Get a fund by ID, including strategy, vintage, currency, target size, status, first and final close dates, owners, tags, and custom fields. Scope: read:funds

Parameter	Type	Required
`id`	string	Yes

`list_fund_tags`

List fund tags so you can pass exact IDs to the tagIds filter on search_funds. Scope: read:funds

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, type, and value, plus color and externalReference when set. Match the label against value and pass the tag’s id to tagIds.

`search_fundraising_processes`

Search fundraising processes. Each result carries its status, stage, target, soft-circled, and committed amounts, probability, expected close date, owners, source, and next steps. Scope: read:fundraising_processes

Parameter	Type	Description
`query`	string	Search text
`fundIds`	string[]	Fund IDs (resolve with `search_funds`)
`limitedPartnerIds`	string[]	LP IDs (resolve with `search_limited_partners`)
`sourceContactIds`	string[]	People who originated the process (resolve with `search_people`)
`ownerUserIds`	string[]	Owner user IDs (resolve with `search_users`)
`tagIds`	string[]	Process tag IDs (resolve with `list_fundraising_process_tags`)
`status`, `stage`	string	A configured label from `get_fundraising_status_and_stages`, or an uppercase internal enum such as `ACTIVE` or `DILIGENCE`
`createdAfter`, `createdBefore`	string	RFC3339 timestamps
`updatedAfter`, `updatedBefore`	string	RFC3339 timestamps
`lastActivityAfter`, `lastActivityBefore`	string	RFC3339 timestamps
`stageChangedAfter`, `stageChangedBefore`	string	When the process entered its current stage (RFC3339). Records without a stage-change time never match
`expectedCloseAfter`, `expectedCloseBefore`	string	RFC3339 timestamps
`sortBy`	string	`statusOrder` or `stageOrder` to sort by the configured pipeline. Omit for relevance order
`sortOrder`	string	`asc` (default) or `desc`. Requires `sortBy`
`page`, `pageSize`	integer	Pagination

A configured label matches only processes that carry that label. An uppercase enum matches every label mapped to it, plus processes created before labels were configured. For time-in-stage questions, set stageChangedBefore. To find processes in one fund that have sat in their current stage for more than 30 days, set stageChangedBefore to the timestamp 30 days before the current time and sort by stage order:

{
  "name": "search_fundraising_processes",
  "arguments": {
    "fundIds": ["507f1f77bcf86cd799439011"],
    "stageChangedBefore": "<RFC3339 timestamp 30 days ago>",
    "sortBy": "stageOrder"
  }
}

`get_fundraising_process`

Get a fundraising process by ID. The record includes fund and LP IDs, status and stage with their configured labels (externalStatus, externalStage), and amounts. It also includes probability, close dates, data room status, owners, notes, tags, and custom fields. Private processes you can’t access return an error. Scope: read:fundraising_processes

Parameter	Type	Required
`id`	string	Yes

`get_fundraising_status_and_stages`

Return your organization’s configured fundraising statuses and stages, with a mapping from each label to its internal enum value. Call it before filtering search_fundraising_processes by status or stage. Scope: read:fundraising_processes Takes no parameters. Active labels come first. archivedStatusLabels and archivedStageLabels list retired labels that still appear on historical processes. Labels that map to more than one internal value appear under ambiguousStatusLabels and ambiguousStageLabels instead of the mapping.

`list_fundraising_process_tags`

List fundraising process tags so you can pass exact IDs to the tagIds filter on search_fundraising_processes. Scope: read:fundraising_processes

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, type, and value, plus color and externalReference when set. Match the label against value and pass the tag’s id to tagIds.

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`. On Items lists (`resourceType: "none"`), add `foreignResourceType` to create a relationship column (see Relationship columns). Other column types (date, currency, enrichment, 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`. On Items lists, include `foreignResourceType` to add a relationship column
`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. To set a relationship column, pass { "sourceId": "<resource ID>" } as the cell value.

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

To set or clear a relationship column, pass { "sourceId": "<resource ID>" } or { "sourceId": "" } as the cell value.

When a column maps to a source resource, updating that cell writes back to the linked deal, company, or person only on lists with write-back enabled. This mutates data outside the list. Confirm intent before calling.

Relationship columns

Items lists (resourceType: "none") can link each row to a Company, Person, or Deal through a relationship column. Use them to track records that relate to several Metal resources, such as a row per meeting with a person column and a deal column. To create one, pass a column with type: "string" and foreignResourceType set to company, person, or deal to create_list or the add array of update_list_columns. Metal configures the column’s name mapping automatically. Relationship columns created through MCP require an Items list.

{
  "name": "update_list_columns",
  "arguments": {
    "id": "507f1f77bcf86cd799439011",
    "add": [
      { "name": "Contact", "type": "string", "foreignResourceType": "person" },
      { "name": "Deal", "type": "string", "foreignResourceType": "deal" }
    ]
  }
}

To fill a relationship cell in add_list_entries or update_list_entry, resolve the resource ID with search_companies, search_people, or search_deals. Then pass { "sourceId": "<resource ID>" } as the value. Pass { "sourceId": "" } to clear the cell. sourceId must be the only key and must be a valid Metal ID. Don’t pass a name. If no matching resource exists, omit the cell.

{
  "name": "update_list_entry",
  "arguments": {
    "listId": "507f1f77bcf86cd799439011",
    "entryId": "507f1f77bcf86cd799439099",
    "values": {
      "60c...contact": { "sourceId": "507f1f77bcf86cd799439012" },
      "60c...deal": { "sourceId": "" }
    }
  }
}

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

Tasks

Task tools let an assistant find, read, update, and delete Metal tasks. Reads require read:tasks. update_task and delete_task require both read:tasks and write:tasks. The Metal API enforces task access on every call, so a caller without access to a task receives an error.

read:tasks and write:tasks must be registered in PropelAuth for your organization before the OAuth authorize step will accept them. If the connection completes but task calls return insufficient scope, ask an org admin to add the missing scope. See the overview callout.

Task-returning tools use this shape. delete_task does not; it returns { "deletedTaskId": "..." }.

{
  "id": "66f1c2a9b1e4a0012a3b4c50",
  "title": "Send NDA to Acme",
  "description": "Follow up after the intro call.",
  "status": "open",
  "dueDate": "2026-10-01T00:00:00Z",
  "assigneeIds": ["507f1f77bcf86cd799439011"],
  "ownerIds": ["507f1f77bcf86cd799439011"],
  "tagIds": [],
  "origin": "user",
  "isPrivate": false,
  "relatedResources": [{ "type": "company", "id": "507f1f77bcf86cd799439012" }],
  "createdAt": "2026-09-20T14:03:00Z",
  "updatedAt": "2026-09-21T09:12:00Z"
}

Responses list the users responsible for a task in assigneeIds, which can hold more than one user. search_tasks filters with assigneeIds. update_task accepts assigneeIds or assigneeId. ownerIds lists the task’s access owners, not every user the task is shared with. Shared users and teams appear in sharedWith. When a task was created from another record, such as a session or workflow run, the result includes createdFrom. Task statuses are open, in_progress, completed, and canceled. Task origins are user, crm, and agent.

`list_tasks`

Browse tasks with structured filters only. Use it to filter by status, due window, one related record, or the record a task was created from. list_tasks does not match title or description text and cannot filter by assignee or owner. Use search_tasks for those. Results page without totalCount or totalPages. Scope: read:tasks

Parameter	Type	Description
`statuses`	string[]	`open`, `in_progress`, `completed`, `canceled`
`dueAfter`	string	RFC3339 timestamp. Includes tasks due at or after it
`dueBefore`	string	RFC3339 timestamp. Includes tasks due before it
`relatedResourceType`, `relatedResourceId`	string	Tasks linked to one record. Pass both together. Types: `company`, `person`, `deal`, `data_entity`, `activity`, `screening`, `limited_partner`, `fund`, `fundraising_process`
`createdFromType`, `createdFromId`	string	Tasks created from one source record, such as a primary resource type, `session`, or `workflow_run`. Pass both together
`page`, `pageSize`	integer	Pagination. `pageSize` defaults to `25`, max `100`

The server rejects an inverted due window. dueAfter must be earlier than or equal to dueBefore, otherwise the call returns dueAfter must be earlier than or equal to dueBefore. Passing only one half of a type and ID pair also returns an error.

{
  "name": "list_tasks",
  "arguments": {
    "statuses": ["open", "in_progress"],
    "relatedResourceType": "company",
    "relatedResourceId": "507f1f77bcf86cd799439012",
    "dueBefore": "2026-10-31T00:00:00Z"
  }
}

`search_tasks`

Search tasks by text and structured filters, including people. Use it when you need to match words in a task’s title or description, or filter by assignee or owner. Results include pagination.totalCount and pagination.totalPages. Scope: read:tasks

Parameter	Type	Description
`query`	string	Words to match in the task title or description
`assigneeIds`	string[]	User IDs responsible for the task, or `"me"` for the signed-in user
`ownerIds`	string[]	Task owner user IDs, or `"me"` for the signed-in user
`statuses`	string[]	`open`, `in_progress`, `completed`, `canceled`
`origins`	string[]	`user`, `crm`, `agent`
`dueAfter`, `dueBefore`	string	RFC3339 due window. `dueAfter` is inclusive and `dueBefore` is exclusive. Inverted windows are rejected
`relatedResourceType`, `relatedResourceId`	string	Tasks linked to one record. Pass both together
`page`, `pageSize`	integer	Pagination. `pageSize` defaults to `25`, max `100`

Resolve user IDs with search_users, or pass "me". Blank entries in assigneeIds or ownerIds return an error.

{
  "name": "search_tasks",
  "arguments": {
    "query": "NDA",
    "assigneeIds": ["me"],
    "statuses": ["open"]
  }
}

`get_task`

Get one task by ID. Returns the same fields as list_tasks and search_tasks. Scope: read:tasks

Parameter	Type	Required
`taskId`	string	Yes. 24-character hex task ID

`update_task`

Patch an existing task. Only the fields you pass are written. Resolve the task ID with list_tasks or search_tasks, and read current values with get_task first. The tool returns the updated task. A call that changes no field returns nothing to update: pass at least one field to change. Scope: read:tasks and write:tasks

Parameter	Type	Description
`taskId`	string	Required. 24-character hex task ID
`title`	string	Replacement title
`description`	string	Replacement description. Use `clearDescription: true` to remove it
`status`	string	`open`, `in_progress`, `completed`, or `canceled`. Set `completed` to mark work done
`dueDate`	string	RFC3339 timestamp or `YYYY-MM-DD`. Use `clearDueDate: true` to remove it
`assigneeIds`	string[]	Replace the assignee list with these user IDs or `"me"`. Use `assigneeId` for a single user, or `clearAssignees: true` to unassign
`owners`	string[]	Replace owners (at least one). Use `addOwners` or `removeOwners` to change owners incrementally
`sharedWith`	object[]	Replace sharing with `{ id, resource, access }` entries, where `resource` is `user` or `team` and `access` is `viewer` or `editor` (default `editor`). Use `addSharedWith` or `removeSharedWith` to change incrementally
`isPrivate`	boolean	`true` limits visibility to owners and shared users or teams. `false` makes the task readable across the organization
`tags`	string[]	Replace task tag IDs. Use `addTags` or `removeTags` to change incrementally
`addRelatedResources`	object[]	Link records as `{ type, id }` without removing existing links
`removeRelatedResources`	object[]	Unlink records matched by `type` and `id`

Each replace argument is mutually exclusive with its add and remove variants. addRelatedResources and removeRelatedResources cannot be passed in the same call. Assignees remain owners of the task. How a task was created (origin and createdFrom) cannot be changed. Prefer the add and remove variants for sharing, owners, and tags. The replacing arguments drop any entries you did not read first.

{
  "name": "update_task",
  "arguments": {
    "taskId": "66f1c2a9b1e4a0012a3b4c50",
    "status": "completed",
    "addRelatedResources": [
      { "type": "deal", "id": "507f1f77bcf86cd799439013" }
    ]
  }
}

`delete_task`

Permanently delete one task by ID. Deletion cannot be undone. Scope: read:tasks and write:tasks

Parameter	Type	Required
`taskId`	string	Yes. 24-character hex task ID

{
  "deletedTaskId": "66f1c2a9b1e4a0012a3b4c50"
}

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

Read the stored current scoring results for one company or deal. The tool doesn’t recalculate or publish scores. Large responses omit reasoning, citations, and provenance when needed to fit the response limit. Scope: read:scores plus read:companies (for companyId) or read:deals (for dealId)

Parameter	Type	Description
`companyId`	string	Company ID
`dealId`	string	Deal ID

Provide exactly one of companyId or dealId.

{
  "name": "get_current_scores",
  "arguments": {
    "companyId": "507f1f77bcf86cd799439011"
  }
}

`get_score_history`

Read one page of stored scoring history for one company or deal, including invalidated events. Use it to see how a score changed over time. Scope: read:scores plus read:companies (for companyId) or read:deals (for dealId)

Parameter	Type	Description
`companyId`	string	Company ID
`dealId`	string	Deal ID
`pageSize`	integer	Records per page (default `10`, max `25`)
`nextToken`	string	`metadata.nextToken` from the prior response

Provide exactly one of companyId or dealId. If a page exceeds the response limit, retry with the same nextToken and a smaller pageSize.

`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

Scoring families and scores

Scoring family tools manage org-defined scoring rules used by workflows. Listing and reading require read:workflows; create, rename, and append require read:workflows and write:workflows.

Tool	Purpose
`list_scoring_families`	List family summaries with cursor pagination
`get_scoring_family`	Get a family and all of its immutable rules versions
`create_scoring_family`	Create an inactive family with its first rules version
`rename_scoring_family`	Rename a family
`append_scoring_family_rules`	Append a new immutable rules version
`propose_scoring_family`	Validate and canonicalize a draft without creating records

Score tools read stored scoring results and handle workflow-generated scores.

Tool	Purpose
`get_current_scores`	Read stored current scores for one company or deal
`get_score_history`	Read one page of stored score history, including invalidated events
`list_pending_workflow_scores`	List validated scores from one run that still need a company or deal target
`publish_pending_workflow_score`	Bind a pending score to a company or deal
`dismiss_pending_workflow_score`	Dismiss a pending score with a required reason

Score reads require read:scores plus the target resource’s read scope (read:companies or read:deals). Pending score tools require read:workflows; publishing or dismissing also requires write:workflow_runs, and publishing checks the target read scope: read:companies with a company id, or read:deals with a deal id.

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. Dashboard read tools use read:dashboards:

Tool	Purpose
`list_dashboards`	List canvas dashboards visible to you, with widget counts
`get_dashboard`	Outline a dashboard’s metadata and widget list
`get_dashboard_widget`	Resolve one widget into rendered structured JSON

refresh_dashboard_widget busts one widget’s cache and re-resolves it; it requires both read:dashboards and write:dashboards. 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

`rerun_workflow_run_from_step`

Start a new run from a chosen step of a finished run, reusing the source run’s input and seeding outputs from every step before the target. The source run must be in a terminal status, and every step before the target must have completed. The rerun uses the workflow’s current definition, so step IDs may have changed if the workflow was edited since the source run.

Parameter	Type	Required	Description
`workflowRunId`	string	Yes	Finished run to rerun from
`stepId`	string	Yes	Step to restart execution from
`dryRun`	boolean	No	Run the new run in dry-run mode

Authoring

Scope: write:workflows These tools create and edit workflows:

Tool	Purpose
`create_workflow`	Create a new workflow, starting as Restricted with a manual trigger
`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
`configure_workflow_scoring`	Set, replace, reorder, or clear the workflow’s scoring configurations
`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, field shapes, and scoring families. 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
`metal://fields/tasks`	Field keys returned by task tools, and the arguments `update_task` accepts
`metal://fields/limited_partners`	Field keys returned by limited partner tools
`metal://fields/funds`	Field keys returned by fund tools
`metal://fields/fundraising_processes`	Field keys returned by fundraising process 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 99 tools (alphabetical)

add_dashboard_widget · add_list_entries · add_workflow_step · append_scoring_family_rules · configure_workflow_input · configure_workflow_output · configure_workflow_scoring · configure_workflow_trigger · create_dashboard · create_list · create_scoring_family · create_workflow · delete_task · delete_workflow_step · dismiss_pending_workflow_score · get_activities · get_activity · get_companies · get_company · get_current_scores · get_current_user · get_custom_field_definitions · get_dashboard · get_dashboard_widget · get_dashboard_widget_source · get_deal · get_deal_status_and_stages · get_document · get_document_page · get_document_types · get_fund · get_fundraising_process · get_fundraising_status_and_stages · get_limited_partner · get_list · get_list_entries · get_person · get_person_context · get_score_history · get_scoring_family · get_scoring_framework · get_screening · get_screening_scores · get_sdk_method · get_task · get_team · get_user · get_workflow · get_workflow_run · get_workflow_run_step · get_workflow_step · list_companies · list_company_tags · list_dashboards · list_documents · list_fund_tags · list_fundraising_process_tags · list_limited_partner_tags · list_lists · list_pending_workflow_scores · list_person_tags · list_scoring_families · list_scoring_frameworks · list_sdk_methods · list_tasks · list_teams · list_workflow_building_options · list_workflow_runs · list_workflows · move_workflow_step · propose_scoring_family · publish_pending_workflow_score · refresh_dashboard_widget · remove_dashboard_widget · rename_scoring_family · reorder_dashboard_widgets · rerun_workflow_run_from_step · review_workflow_hitl_step · run_workflow · search_companies · search_company_taxonomy · search_deals · search_documents · search_fundraising_processes · search_funds · search_limited_partners · search_people · search_screenings · search_tasks · search_users · update_dashboard · update_dashboard_widget · update_deal_status_and_stage · update_list · update_list_columns · update_list_entry · update_task · update_workflow_details · update_workflow_step

When programmatic queries are enabled for your organization, the server also exposes run_metal_sdk_query when the read:programmatic scope is granted.

​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

​search_company_taxonomy

​Custom fields

​get_custom_field_definitions

​Documents

​search_documents

​get_document

​Other document tools

​get_document_page

​People

​search_people

​list_person_tags

​get_person

​get_person_context

​Deals

​search_deals

​get_deal

​get_deal_status_and_stages

​update_deal_status_and_stage

​Investor relations

​search_limited_partners

​get_limited_partner

​list_limited_partner_tags

​search_funds

​get_fund

​list_fund_tags

​search_fundraising_processes

​get_fundraising_process

​get_fundraising_status_and_stages

​list_fundraising_process_tags

​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

​Relationship columns

​Activities

​get_activities

​get_activity

​Tasks

​list_tasks

​search_tasks

​get_task

​update_task

​delete_task

​Screenings and scoring

​search_screenings

​get_screening

​get_screening_scores

​list_scoring_frameworks

​get_current_scores

​get_score_history

​get_scoring_framework

​Scoring families and scores

​Dashboards

​create_dashboard

​update_dashboard

​add_dashboard_widget

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`

`search_company_taxonomy`

Custom fields

`get_custom_field_definitions`

Documents

`search_documents`

`get_document`

Other document tools

`get_document_page`

People

`search_people`

`list_person_tags`

`get_person`

`get_person_context`

Deals

`search_deals`

`get_deal`

`get_deal_status_and_stages`

`update_deal_status_and_stage`

Investor relations

`search_limited_partners`

`get_limited_partner`

`list_limited_partner_tags`

`search_funds`

`get_fund`

`list_fund_tags`

`search_fundraising_processes`

`get_fundraising_process`

`get_fundraising_status_and_stages`

`list_fundraising_process_tags`

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`

Relationship columns

Activities

`get_activities`

`get_activity`

Tasks

`list_tasks`

`search_tasks`

`get_task`

`update_task`

`delete_task`

Screenings and scoring

`search_screenings`

`get_screening`

`get_screening_scores`

`list_scoring_frameworks`

`get_current_scores`

`get_score_history`

`get_scoring_framework`

Scoring families and scores

Dashboards

`create_dashboard`

`update_dashboard`

`add_dashboard_widget`