Tool Catalog

Complete reference for all DealSurface MCP tools. Each tool maps to a REST API endpoint.

For detailed request/response schemas and code examples, see the REST API Reference.

list_products

scope: readFree

List active products configured for your team. This is typically the first tool called in any workflow. Disabled products are hidden unless include_disabled is true.

Inputs

Parameter	Type	Description
`include_disabled`	`boolean`	Include disabled product metadata. Defaults to false.

Output

{
  products: Array<{
    product_id: number
    name: string
    description: string
    is_active: boolean
    keywords: Array<{ keyword_id, name, auto_extracted }>
    sources: Array<{ source_id, url, title, source_type }>
    industries: Array<{ industry_name, industry_description, industry_code }>
  }>
}

Common failures

•401 — Invalid API key.
•403 — Key lacks `read` scope.

Sequencing

Start here. Use the returned product_id with list_prospects or get_prospect.

get_product

scope: readFree

Get detailed information about a specific active product, including its keywords, sources, and target industries. Disabled products are hidden unless include_disabled is true.

Inputs

Parameter	Type	Description
`product_id`required	`number`	The product ID.
`include_disabled`	`boolean`	Include disabled product metadata. Defaults to false.

Output

{
  product: {
    product_id: number
    name: string
    description: string
    is_active: boolean
    keywords: [...]
    sources: [...]
    industries: [...]
  }
}

Common failures

•404 — Product not found, disabled without include_disabled, or belongs to a different team.

Sequencing

Use after list_products if you need full details on a single product.

list_prospects

scope: readFree

Get assessed companies ranked by deal score for a product. Returns paginated results sorted by score.

Inputs

Parameter	Type	Description
`product_id`required	`number`	Product to get prospects for.
`min_deal_score`	`number`	Minimum deal score (1-5). `12345`
`min_buying_signal`	`number`	Minimum buying signal (0.0-1.0).
`limit`	`number`= 100	Max results (1-500).
`offset`	`number`= 0	Pagination offset.

Output

{
  prospects: Array<{ ticker, company_name, deal_score, rank, rank_total }>
  total_count: number
  limit: number
  offset: number
}

Common failures

•400 — Invalid product_id or filter parameters.
•404 — Product not found.

Sequencing

Call after list_products. Use ticker values with get_prospect for deep dives.

get_prospect

scope: readFree

Full prospect analysis including findings, recommendations, and evidence excerpts for a company and product.

Inputs

Parameter	Type	Description
`ticker`required	`string`	Company ticker symbol.
`product_id`required	`number`	Product context.

Output

{
  ticker, company_name, deal_score, rank, rank_total,
  findings_summary, recommendation_summary,
  key_opportunity, primary_challenge,
  impact_score_distribution: { "5": n, "4": n, ... },
  findings: Array<{ finding_id, text, evidence_excerpt_ids }>,
  excerpts: Array<{ excerpt_id, text, impact_score, framework_category, source, pain_points, buying_signal_present }>
}

Common failures

•404 — No cached prospect data for this company/product.
•400 — Invalid ticker or product_id.

Sequencing

Call after list_prospects to research a specific company. Follow with search_excerpts for filtering.

search_excerpts

scope: readFree

Search and filter evidence excerpts for a prospect. Use this for granular evidence analysis beyond what get_prospect returns.

Inputs

Parameter	Type	Description
`product_id`required	`number`	Product context.
`ticker`required	`string`	Company ticker symbol.
`min_impact_score`	`number`	Minimum impact score (1-5).
`framework_category`	`string`	Filter by category. `Strategic IntentMetric IntentMarket Topics`
`keyword`	`string`	Filter by keyword in pain_points.
`limit`	`number`= 50	Max results (1-200).
`offset`	`number`= 0	Pagination offset.

Output

{
  excerpts: Array<{ excerpt_id, text, impact_score, framework_category, source, pain_points, sales_summary, buying_signal_present }>
  total_count: number
  limit: number
  offset: number
}

Common failures

•404 — No cached prospect data.
•400 — Invalid framework_category value.

Sequencing

Use after get_prospect for deeper evidence analysis. Excerpt IDs can be referenced in craft_outreach results.

get_dealmap

scope: readFree

Get the buying committee DealMap for a prospect company. Shows stakeholders with AI-assigned roles (Economic Buyer, Decision Maker, Champion, etc.), org hierarchy edges, and a buying_committee_summary identifying the top pick for each role.

Inputs

Parameter	Type	Description
`product_id`required	`number`	Product context.
`ticker`required	`string`	Company ticker symbol.

Output

{
  status: "empty" | "ready" | "stale"
  chart: { id, generated_at, expires_at, company_name, node_count, relevant_node_count } | null
  stakeholders: Array<{
    node_id, full_name, title, level, level_label,
    linkedin_url, work_email, manager_name,
    stakeholder_role, stakeholder_role_source,
    annotation_score, annotation_reason,
    is_top_pick, top_pick_source
  }>
  edges: Array<{ from_node_id, to_node_id, relationship }>
  buying_committee_summary: {
    economic_buyer, decision_maker, champion,
    executive_sponsor, evaluator, blockers: [...]
  }
}

Common failures

•400 — Invalid product_id or ticker.
•404 — Product not found.

Sequencing

Call after get_prospect. Returns status 'empty' if no DealMap exists yet — call generate_dealmap first.

generate_dealmap

scope: read, outreach0-10 credits

Generate or refresh the buying committee DealMap for a prospect. Maps the org structure and assigns stakeholder roles using AI analysis. Credits charged only when fresh org-chart data is fetched.

Inputs

Parameter	Type	Description
`product_id`required	`number`	Product context.
`ticker`required	`string`	Company ticker symbol.
`force_refresh`	`boolean`= false	Force fresh org chart fetch. Always charges credits.

Output

{
  status: "ready"
  chart: { id, generated_at, expires_at, company_name, node_count, relevant_node_count }
  stakeholders: Array<{ node_id, full_name, title, level, stakeholder_role, is_top_pick, ... }>
  edges: Array<{ from_node_id, to_node_id, relationship }>
  buying_committee_summary: { economic_buyer, decision_maker, champion, ... }
  generation_source: "org_fresh" | "org_cached" | "annotation_only"
  credits_charged: boolean
}

Common failures

•402 — Insufficient credits for fresh generation.
•404 — Product not found.
•502 — DealMap generation service temporarily unavailable.

Sequencing

Call after get_prospect. Follow with get_dealmap to read the result, or use stakeholders directly with craft_outreach.

Avoid unnecessary force_refresh

The MCP tool documentation strongly recommends against using force_refresh unless the user explicitly requests updated org data. Cached org-chart data is reused for free.

override_stakeholder_role

scope: read, outreachFree

Override the AI-assigned stakeholder role for a specific person on the buying committee DealMap. This is a team-wide override visible to all team members. Use when the AI role assignment is clearly wrong.

Inputs

Parameter	Type	Description
`product_id`required	`number`	Product context.
`ticker`required	`string`	Company ticker symbol.
`node_id`required	`string`	The node_id from get_dealmap stakeholders.
`stakeholder_role`required	`string`	The corrected stakeholder role. `Economic BuyerDecision MakerChampionExecutive SponsorEvaluatorEnd UserProcurement / Legal ReviewerBlockerIrrelevant`

Output

{
  success: true
  node_id: string
  stakeholder_role: string
}

Common failures

•400 — Invalid node_id or stakeholder_role.
•404 — Product not found or node not in DealMap.

Sequencing

Call after get_dealmap when an AI-assigned role needs correction.

craft_outreach

scope: read, outreach1 credit

Generate an evidence-backed outreach message (email or LinkedIn) for a prospect. Grounded in real evidence from public filings and earnings calls.

Inputs

Parameter	Type	Description
`product_id`required	`number`	Product context.
`ticker`required	`string`	Company ticker symbol.
`platform`required	`string`	Target platform. `emaillinkedin`
`tone`required	`string`	Desired tone. `hard_sellhelpfulneutral`
`length`	`string`= typical	Desired length. `shortertypicallonger`
`selected_lead`	`SelectedLead`	Full lead object to personalize for.
`lead_selector`	`object`	Selector to resolve a stakeholder: { node_id }, { level }, { full_name, level }, or { stakeholder_role }.

Output

{
  subject?: string   // Only for email platform
  body: string
  platform: string
  tone: string
  length: string
  used_excerpt_ids: number[]
  selected_lead?: { full_name, title, level }
  selected_lead_note?: string
}

Common failures

•402 — Insufficient credits.
•404 — No cached prospect data.
•400 — Invalid platform, tone, or length value.

Sequencing

Final step in a workflow. Use stakeholders from get_dealmap and evidence from get_prospect or search_excerpts.

Lead targeting

If both selected_lead and lead_selector are provided, selected_lead takes precedence. Omit both for generic company outreach.

Installation & Setup Workflows