# CB Insights MCP server

We offer a hosted **[MCP](https://modelcontextprotocol.io/introduction) server** at [`mcp.cbinsights.com`](https://mcp.cbinsights.com) that enables AI assistants to securely access CB Insights data and capabilities on demand.

> _**Deprecation notice:** The [self-hosted alternative on Github](https://www.github.com/cbinsights/cbi-mcp-server) is deprecated as of January 2026. Please use the hosted MCP server at `https://mcp.cbinsights.com` instead._

## Programmatic access

In addition to the default user-specific auth flow (OAuth `authorization_code` grant type) used by clients like ChatGPT, Claude, and Microsoft Copilot, the CB Insights MCP server also supports a machine-to-machine auth flow (OAuth `client_credentials` grant type) designed for programmatic access.

To leverage this capability, configure your script to authenticate via `client_credentials` OAuth flow using the same `client_id` and `client_secret` you use for [authorizing against the CB Insights API](https://api-docs.cbinsights.com/v2/#tag/Authorization).

Example:
```bash
# Get an access token
curl -X POST https://mcp.cbinsights.com/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"
```

## Tools reference

**40 tools** across 3 categories:

- **Entity Data Tools** (21)
- **Search Tools** (6)
- **Other Tools** (13)

---

### Entity Data Tools

Retrieve detailed data for a specific company or investor.

#### Get Company Acquisitions – `get_company_acquisitions`

For each of the requested companies or investors, returns acquisitions, M&A deals, mergers, buyouts, and takeovers, ordered by recency.

Use `search_deals` for M&A deal filtering capabilities, including 50+ attribute filters.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `selector` | `any` |  | Set of orgs to fetch acquisitions for. Accepts org_ids, org_names, competitors_of (ids or names), market_ids, and watchlist targeting (watchlist_ids, my_watchlists, my_competitors); the union is deduped. The set is capped to bound fan-out. Returns a list of results plus any unresolved inputs in `errors`. |
| `preset` | `string` |  | Field preset: 'concise' (default — omits the heavy per-deal `mentions` detail) or 'full' (includes it). |
| `limit` | `integer` | `20` | Maximum number of acquisitions to return per company |
| `offset` | `integer` | `0` | Offset for pagination (applied per company) |
| `id_org` | `integer` |  | DEPRECATED — use selector.org_ids=[id] instead. Single CBI entity ID. |
| `org_name` | `string` |  | DEPRECATED — use selector.org_names=[name] instead. Single company or investor name. |
| `verbose` | `boolean` | `False` | DEPRECATED — use preset='full' instead. When true, includes the full per-deal `mentions` detail. |

---

#### Get Company Analyst Ratings – `get_company_analyst_ratings`

For each of the requested companies, returns its CB Insights analyst rating 
 (optimistic, neutral, or cautious) — the verdict CBI's analysts publish on a 
 company's outlook — plus the analyst's written rationale.

Analyst ratings cover a curated subset of companies, so many companies have no 
 rating; those come back with an `error` saying so rather than an empty payload.

Fields returned: 
 - analyst_rating: the company's current rating. Every field below is omitted
  when the analysts have not set it, so a sparse object is expected.
  - rating: the verdict — optimistic, neutral, or cautious.
  - status: how live the verdict is — live (actively maintained),
    under_review (being revisited), coming_soon (rating in progress, no
    verdict yet), or no_longer_rating (coverage dropped; the verdict is
    historical). Treat anything other than live as stale.
  - ts_rating: when the rating was last set.
  - description: a short summary blurb about the rating.
  - note: the analyst's written rationale, with title, thesis (the core
    argument), signals (a list of {name, content} evidence points backing
    the thesis), and what_analysts_are_watching_for (what would change
    their mind). 
 - rating_history: every recorded change to the rating, newest first. Only
  present when preset='full'; an empty list means no changes were recorded.
  Each entry has change_type (initiated, reaffirmed, upgraded, or
  downgraded), rating (the verdict as of that change), and ts_rating (when
  the change was made).

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `selector` | `any` |  | Set of orgs to fetch analyst ratings for. Accepts org_ids, org_names, competitors_of (ids or names), market_ids, and watchlist targeting (watchlist_ids, my_watchlists, my_competitors); the union is deduped. The set is capped to bound fan-out. Returns a list of results plus any unresolved inputs in `errors`. |
| `preset` | `string` |  | Detail preset: 'concise' (the current rating — the default) or 'full' (also fetches and includes the rating change history). |

---

#### Get Company Buyer Transcripts – `get_company_buyer_transcripts`

Return buyer/customer interview transcripts about a company — interviews 
 with software buyers describing their evaluation, purchase, and experience 
 with the company's products. Use when the user asks for qualitative buyer 
 feedback, customer interviews, voice-of-customer content, or firsthand 
 accounts of a company's products.

Returns up to `limit` transcripts (default 20). Pass `limit=null` to 
 return every available transcript — useful when the user asks for "all" 
 buyer interviews or wants comprehensive voice-of-customer coverage.

Fields returned: 
 - transcripts: list of buyer interview transcripts. Each transcript has:
  - transcript_id: stable identifier for the transcript.
  - title: title of the interview transcript.
  - event_date: date the interview took place (ISO format, may be empty).
  - content: full body of the interview transcript.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `id_org` | `integer` |  | CBI entity ID (id_org/id_cbi_entity, if known). Provide this OR org_name. |
| `org_name` | `string` |  | Company name to look up. Provide this OR id_org. |
| `limit` | `integer` | `20` | Max transcripts to return. Default 20. Pass null to return all. |

---

#### Get Company Cap Table – `get_company_cap_table`

For each of the requested companies, returns its cap table history: per-round 
 share class terms sourced from state incorporation filings (certificate of 
 incorporation), sorted by round. Includes shares authorized, par value, issuance 
 price, liquidation preference and amount, conversion price, dividend terms, 
 participation rights, anti-dilution provisions, voting rights, and percent 
 owned when available. Primarily covers private US companies; many companies 
 have no cap table data.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `selector` | `any` |  | Set of orgs to fetch cap table history for. Accepts org_ids, org_names, competitors_of (ids or names), market_ids, and watchlist targeting (watchlist_ids, my_watchlists, my_competitors); the union is deduped. The set is capped to bound fan-out. Returns a list of results plus any unresolved inputs in `errors`. |
| `limit` | `integer` | `20` | Maximum number of cap table rounds to return per company |
| `offset` | `integer` | `0` | Offset for pagination (applied per company) |
| `id_org` | `integer` |  | DEPRECATED — use selector.org_ids=[id] instead. Single CBI entity ID. |
| `org_name` | `string` |  | DEPRECATED — use selector.org_names=[name] instead. Single company name. |

---

#### Get Company Competitors – `get_company_competitors`

For each of the requested companies, returns its competitors, similar companies, peers, challengers, and incumbents.

To filter competitors by product type and 50+ attributes, use `search_companies` tool.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `selector` | `any` |  | Set of orgs to fetch competitors for. Accepts org_ids, org_names, competitors_of (ids or names), market_ids, and watchlist targeting (watchlist_ids, my_watchlists, my_competitors); the union is deduped. The set is capped to bound fan-out. Returns a list of results plus any unresolved inputs in `errors`. |
| `preset` | `string` |  | Field preset: 'concise' (default — each competitor's identity, url, stage, Mosaic score, relevancy, and rank) or 'full' (also includes description, funding, and logo). |
| `limit` | `integer` | `25` | Maximum number of competitors to return per company |
| `offset` | `integer` | `0` | Offset for pagination (applied per company) |
| `include_guidance` | `boolean` | `True` | Include explanatory guidance for score fields |
| `id_org` | `integer` |  | DEPRECATED — use selector.org_ids=[id] instead. Single CBI entity ID. |
| `org_name` | `string` |  | DEPRECATED — use selector.org_names=[name] instead. Single company or investor name. |

---

#### Get Company Exits – `get_company_exits`

For each of the requested companies or investors, returns its exits (e.g. IPOs, 
 mergers, acquisitions, going public, dissolutions, SPACs, buyouts, and other 
 liquidity events).

To search exits across companies with 50+ filters, use the `search_companies` tool.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `selector` | `any` |  | Set of orgs to fetch exits for. Accepts org_ids, org_names, competitors_of (ids or names), market_ids, and watchlist targeting (watchlist_ids, my_watchlists, my_competitors); the union is deduped. The set is capped to bound fan-out. Returns a list of results plus any unresolved inputs in `errors`. |
| `preset` | `string` |  | Field preset: 'concise' (default — omits the heavy per-exit `mentions` detail) or 'full' (includes it). |
| `start_date` | `string` |  | Start date filter (inclusive), format YYYY-MM-DD |
| `end_date` | `string` |  | End date filter (inclusive), format YYYY-MM-DD |
| `limit` | `integer` | `20` | Maximum number of exits to return per company |
| `offset` | `integer` | `0` | Offset for pagination (applied per company) |
| `id_org` | `integer` |  | DEPRECATED — use selector.org_ids=[id] instead. Single CBI entity ID. |
| `org_name` | `string` |  | DEPRECATED — use selector.org_names=[name] instead. Single company or investor name. |
| `verbose` | `boolean` | `False` | DEPRECATED — use preset='full' instead. When true, includes the full per-exit `mentions` detail. |

---

#### Get Company Funding – `get_company_funding`

For each of the requested companies or investors, returns its funding rounds 
 (e.g. pre-seed, seed, Series A-F, growth, late-stage), including round dates, 
 amounts, lead and participating investors, and valuation ranges when available.

For multi-company searches with 50+ attribute filters, use `search_deals` tool.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `selector` | `any` |  | Set of orgs to fetch funding rounds for. Accepts org_ids, org_names, competitors_of (ids or names), market_ids, and watchlist targeting (watchlist_ids, my_watchlists, my_competitors); the union is deduped. The set is capped to bound fan-out. Returns a list of results plus any unresolved inputs in `errors`. |
| `preset` | `string` |  | Field preset: 'concise' (default — omits the heavy per-round `mentions` detail) or 'full' (includes it). |
| `limit` | `integer` | `20` | Maximum number of funding rounds to return per company |
| `offset` | `integer` | `0` | Offset for pagination (applied per company) |
| `id_org` | `integer` |  | DEPRECATED — use selector.org_ids=[id] instead. Single CBI entity ID. |
| `org_name` | `string` |  | DEPRECATED — use selector.org_names=[name] instead. Single company or investor name. |
| `verbose` | `boolean` | `False` | DEPRECATED — use preset='full' instead. When true, includes the full per-round `mentions` detail. |

---

#### Get Company Funding Window – `get_company_funding_window`

Predict when companies will raise their next funding round (funding window, 
 fundraise timing, likelihood to raise, next round prediction).

Returns the predicted fundraising window (start and end date), the 
 company's current phase relative to that window (pre/in/post), the peer 
 cohort of similar companies used to derive the prediction, the percentage 
 of peer companies that historically raised a next round, and the median 
 days to next funding. Use preset='full' to also include the time-to-funding 
 histogram.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `selector` | `any` |  | Set of orgs to predict funding windows for. Accepts org_ids, org_names, competitors_of (ids or names), market_ids, and watchlist targeting (watchlist_ids, my_watchlists, my_competitors); the union is deduped. The set is capped to bound fan-out. Returns a list of results plus any unresolved inputs in `errors`. |
| `preset` | `string` |  | Field preset: 'concise' (phase, predicted window, last funding, peer cohort — the default) or 'full' (also fetches and includes the time-to-funding histogram). |
| `verbose` | `boolean` | `False` | DEPRECATED — use preset='full' instead. When true, includes the time-to-funding histogram. |
| `id_org` | `integer` |  | DEPRECATED — use selector.org_ids=[id] instead. |
| `org_name` | `string` |  | DEPRECATED — use selector.org_names=[name] instead. |

---

#### Get Company Headcount – `get_company_headcount`

Return structured quantitative metrics about a company's employee count and 
 open job postings. Use when the user asks for specific numbers such as headcount, 
 headcount growth rates, number of open positions, or momentum score. Do NOT use 
 for questions about hiring strategy, workforce strategy, talent philosophy, 
 workforce trends, or hiring outlook — use `get_company_hiring_insights` for those.

Fields returned: 
 - total_headcount, total_headcount_as_of: most recent total employee count and
  the date it was measured. 
 - six_month_growth_pct, one_year_growth_pct, two_year_growth_pct: headcount
  growth over the trailing 6 months / 1 year / 2 years, as a percentage. 
 - headcount_history: monthly total headcount over the past 2 years
  (oldest to newest). Each point has as_of_date, headcount, and
  percent_change_pct (change from the prior data point, when available). 
 - department_distribution, country_distribution: object with as_of_date
  and a points list. Each point has name, headcount, and pct_of_total
  (the headcount as a percentage of the sum of all categorized headcounts
  in that distribution; sums to ~100). Sorted by headcount descending. 
 - open_positions: count of open job postings for the most recent target month. 
 - target_month: month that hiring stats (open positions, momentum) were
  captured. 
 - hiring_intensity: percentage of open job positions to total headcount,
  indicating the company's hiring rate relative to its current workforce size. 
 - momentum_score: a CBI proprietary index used to compare hiring activity
  across companies, accounting for company size. A larger company hiring at
  the same rate of job openings as a percentage of total headcount will have
  a higher momentum score than a smaller company with the same rate. The
  average momentum score is around 5 out of 100. 
 - momentum_score_percentile: the percentile ranking of a company's momentum
  score compared to all other companies in the dataset, indicating what
  percentage of companies have lower momentum scores. For example, a company
  in the 99th percentile means 99% of other companies have lower momentum
  scores, placing it in the top 1% of hiring momentum.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `selector` | `any` |  | Set of orgs to fetch headcount metrics for. Accepts org_ids, org_names, competitors_of (ids or names), market_ids, and watchlist targeting (watchlist_ids, my_watchlists, my_competitors); the union is deduped. The set is capped to bound fan-out. Returns a list of results plus any unresolved inputs in `errors`. |
| `preset` | `string` |  | Field preset: 'concise' (current + growth + momentum scalars — the default, and best for comparing across a large set) or 'full' (everything, including the bulky headcount history and department / country distribution lists). |
| `id_org` | `integer` |  | DEPRECATED — use selector.org_ids=[id] instead. |
| `org_name` | `string` |  | DEPRECATED — use selector.org_names=[name] instead. |

---

#### Get Company Hiring Insights – `get_company_hiring_insights`

Return AI-generated narratives about companies' hiring activity, talent 
 strategy, workforce trends, and hiring outlook, based on CB Insights analysis.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `selector` | `any` |  | Set of orgs to fetch hiring insights for. Accepts org_ids, org_names, competitors_of (ids or names), market_ids, and watchlist targeting (watchlist_ids, my_watchlists, my_competitors); the union is deduped. The set is capped to bound fan-out. Returns a list of results plus any unresolved inputs in `errors`. |
| `id_org` | `integer` |  | DEPRECATED — use selector.org_ids=[id] instead. |
| `org_name` | `string` |  | DEPRECATED — use selector.org_names=[name] instead. |

---

#### Get Company Investments – `get_company_investments`

For each of the requested companies or investors, returns its investments 
 (rounds it has backed, led, or co-invested in), including the portfolio company, 
 round type, date, and amount.

To filter investments across investors with 50+ attribute filters, use the 
 `search_deals` tool.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `selector` | `any` |  | Set of orgs to fetch investments for. Accepts org_ids, org_names, competitors_of (ids or names), market_ids, and watchlist targeting (watchlist_ids, my_watchlists, my_competitors); the union is deduped. The set is capped to bound fan-out. Returns a list of results plus any unresolved inputs in `errors`. |
| `preset` | `string` |  | Field preset: 'concise' (default — omits the heavy per-investment `mentions` detail) or 'full' (includes it). |
| `limit` | `integer` | `20` | Maximum number of investments to return per company |
| `offset` | `integer` | `0` | Offset for pagination (applied per company) |
| `id_org` | `integer` |  | DEPRECATED — use selector.org_ids=[id] instead. Single CBI entity ID. |
| `org_name` | `string` |  | DEPRECATED — use selector.org_names=[name] instead. Single company or investor name. |
| `verbose` | `boolean` | `False` | DEPRECATED — use preset='full' instead. When true, includes the full per-investment `mentions` detail. |

---

#### Get Company Investors – `get_company_investors`

For each of the requested companies, returns the investors (e.g. VCs, angels, 
 lead investors, participating investors, backers) who have funded it, including 
 round participation details and lead investor status.

To filter investors by type, geography, fund size, or 50+ other attributes, use 
 `search_investors` instead.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `selector` | `any` |  | Set of orgs to fetch investors for. Accepts org_ids, org_names, competitors_of (ids or names), market_ids, and watchlist targeting (watchlist_ids, my_watchlists, my_competitors); the union is deduped. The set is capped to bound fan-out. Returns a list of results plus any unresolved inputs in `errors`. |
| `limit` | `integer` | `20` | Maximum number of investors to return per company |
| `offset` | `integer` | `0` | Offset for pagination (applied per company) |
| `id_org` | `integer` |  | DEPRECATED — use selector.org_ids=[id] instead. Single CBI entity ID. |
| `org_name` | `string` |  | DEPRECATED — use selector.org_names=[name] instead. Single company or investor name. |

---

#### Get Company Markets – `get_company_markets`

For each of the requested companies, returns the market maps (e.g. industry 
 landscapes, sectors, ESP categories, verticals, segments) that include it, with 
 the market name, description, and associated industries.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `selector` | `any` |  | Set of orgs to fetch market maps for. Accepts org_ids, org_names, competitors_of (ids or names), market_ids, and watchlist targeting (watchlist_ids, my_watchlists, my_competitors); the union is deduped. The set is capped to bound fan-out. Returns a list of results plus any unresolved inputs in `errors`. |
| `id_org` | `integer` |  | DEPRECATED — use selector.org_ids=[id] instead. Single CBI entity ID. |
| `org_name` | `string` |  | DEPRECATED — use selector.org_names=[name] instead. Single company or investor name. |

---

#### Get Company News – `get_company_news`

For each of the requested companies or investors, returns recent news articles 
 (e.g. press releases, announcements, headlines, media coverage, mentions), 
 including dates, titles, content snippets, source URLs, and other organizations 
 mentioned in the same articles.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `selector` | `any` |  | Set of orgs to fetch news for. Accepts org_ids, org_names, competitors_of (ids or names), market_ids, and watchlist targeting (watchlist_ids, my_watchlists, my_competitors); the union is deduped. The set is capped to bound fan-out. Returns a list of results plus any unresolved inputs in `errors`. |
| `limit` | `integer` | `10` | Maximum number of news articles to return per company |
| `offset` | `integer` | `0` | Offset for pagination (applied per company) |
| `start_date` | `string` |  | Start date filter (inclusive), format YYYY-MM-DD |
| `end_date` | `string` |  | End date filter (inclusive), format YYYY-MM-DD |
| `max_content_length` | `integer` | `500` | Maximum character length for article content. Set to null for full text. |
| `id_org` | `integer` |  | DEPRECATED — use selector.org_ids=[id] instead. Single CBI entity ID. |
| `org_name` | `string` |  | DEPRECATED — use selector.org_names=[name] instead. Single company or investor name. |

---

#### Get Company Outlook – `get_company_outlook`

For each of the requested companies, returns forward-looking outlook data: 
 Mosaic scores (with insights, percentiles, and 1-year deltas), exit probability 
 (IPO/M&A) with contributing signals, and commercial maturity / technology 
 readiness levels (TRL).

Mosaic is a 0-1000 health/growth score for private companies (>600 signals a 
 higher likelihood of IPO, unicorn status, or favorable exit).

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `selector` | `any` |  | Set of orgs to fetch outlook data for. Accepts org_ids, org_names, competitors_of (ids or names), market_ids, and watchlist targeting (watchlist_ids, my_watchlists, my_competitors); the union is deduped. The set is capped to bound fan-out. Returns a list of results plus any unresolved inputs in `errors`. |
| `preset` | `string` |  | Field preset: 'mosaic_only' (just Mosaic scores across the set), 'concise' (mosaic + exit_probability + maturity, the default), or 'full' (also includes the full Mosaic score history per company). Score guidance is controlled separately by `include_guidance`. |
| `id_org` | `integer` |  | DEPRECATED — use selector.org_ids=[id] instead. Single CBI entity ID. |
| `org_name` | `string` |  | DEPRECATED — use selector.org_names=[name] instead. Single company or investor name. |
| `include_guidance` | `boolean` | `True` | Include explanatory guidance for score fields |
| `verbose` | `boolean` | `False` | DEPRECATED — use preset='full' instead. When true, includes the full Mosaic score history. |

---

#### Get Company Profile – `get_company_profile`

Return profile overviews for companies or investors: name, description, website, 
 HQ location, founded year, status (e.g. alive, acquired, IPO, dead), total funding, 
 Mosaic score, headcount, sector/industry classification, market maps, and the 
 CB Insights analyst rating when available.

Use this to look up a single company/investor, or to fetch many at once — e.g. to 
 populate a table or compare a set of companies side by side.

To find or filter companies and investors by 50+ attributes (rather than look up ones 
 you can already name or identify), use `search_companies` or `search_investors`.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `selector` | `any` |  | Set of orgs to fetch profiles for. Accepts org_ids, org_names, competitors_of (ids or names), market_ids, and watchlist targeting (watchlist_ids, my_watchlists, my_competitors); the union is deduped. The set is capped to bound fan-out. Returns a list of results plus any unresolved inputs in `errors`. |
| `preset` | `string` |  | Field preset controlling how much of each profile to return — strongly recommended for large selections to stay under response-size limits. One of: 'scores_only' (mosaic + funding), 'concise' (overview + mosaic + funding, where overview covers identity fields like name, description, url, founded year, status, and taxonomy), or 'full' (everything, the default). Score guidance is controlled separately by `include_guidance`. |
| `fields` | `array` |  | DEPRECATED and ignored — use `preset` instead. Accepted for backward compatibility with cached tool manifests; it has no effect, so the response may include more sections than requested. |
| `id_org` | `integer` |  | DEPRECATED — use selector.org_ids=[id] instead. Single CBI entity ID; folded into the selector when provided. |
| `org_name` | `string` |  | DEPRECATED — use selector.org_names=[name] instead. Single company or investor name; folded into the selector when provided. |
| `include_guidance` | `boolean` | `True` | Include explanatory guidance for score fields |

---

#### Get Company Relationships – `get_company_relationships`

For each of the requested companies, returns its business relationships 
 (e.g. partnerships, suppliers, customers, vendors, licensees), ordered by recency.

To filter by relationship type (i.e. client of company, integration partners), 
 industry, or 50+ attributes to find connections between specific companies, use 
 `search_partnerships` instead.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `selector` | `any` |  | Set of orgs to fetch business relationships for. Accepts org_ids, org_names, competitors_of (ids or names), market_ids, and watchlist targeting (watchlist_ids, my_watchlists, my_competitors); the union is deduped. The set is capped to bound fan-out. Returns a list of results plus any unresolved inputs in `errors`. |
| `preset` | `string` |  | Field preset: 'concise' (default — omits the heavy per-relationship `sources` detail) or 'full' (includes it). |
| `limit` | `integer` | `20` | Maximum number of relationships to return per company |
| `offset` | `integer` | `0` | Offset for pagination (applied per company) |
| `id_org` | `integer` |  | DEPRECATED — use selector.org_ids=[id] instead. Single CBI entity ID. |
| `org_name` | `string` |  | DEPRECATED — use selector.org_names=[name] instead. Single company or investor name. |
| `verbose` | `boolean` | `False` | DEPRECATED — use preset='full' instead. When true, includes the full per-relationship `sources` detail. |

---

#### Get Company Revenue – `get_company_revenue`

For each of the requested companies, returns revenue data, including estimated 
 and reported revenue figures, revenue ranges, and historical revenue when available.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `selector` | `any` |  | Set of orgs to fetch revenue data for. Accepts org_ids, org_names, competitors_of (ids or names), market_ids, and watchlist targeting (watchlist_ids, my_watchlists, my_competitors); the union is deduped. The set is capped to bound fan-out. Returns a list of results plus any unresolved inputs in `errors`. |
| `preset` | `string` |  | Field preset: 'concise' (just the revenue KPIs across the set) or 'full' (revenue_by_year + kpis, the default). |
| `id_org` | `integer` |  | DEPRECATED — use selector.org_ids=[id] instead. |
| `org_name` | `string` |  | DEPRECATED — use selector.org_names=[name] instead. |

---

#### Get Company Strategy Map – `get_company_strategy_map`

Get a strategy map showing a company's partnerships, investments, and acquisitions.

Returns the company's strategic relationships grouped into AI-generated 
 categories. Each company in the map includes relationship type 
 (acquisition, investment, or partnership), connection date, headline, 
 and details.

The companion MCP App renders this as an interactive visual map with 
 the anchor company on the left and categories branching to the right, 
 with color-coded chips for each relationship type.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `id_org` | `integer` |  | CBI entity ID (id_org/id_cbi_entity). Provide this OR org_name. |
| `org_name` | `string` |  | Company or investor name to look up. Provide this OR id_org. |

---

#### Get Earnings Call Transcript – `get_earnings_call_transcript`

Return the full transcript for a single earnings call (quarterly results, 
 analyst call, investor call) for a public company, including all speaker 
 paragraphs in order. Defaults to the most recent earnings call.

To compare multiple earnings periods, call this tool in parallel once per period.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `id_org` | `integer` |  | CBI entity ID (id_org/id_cbi_entity, if known). Provide this OR org_name. |
| `org_name` | `string` |  | Company or investor name to look up. Provide this OR id_org. |
| `year` | `integer` |  | Fiscal year of the earnings call (e.g. 2024). When omitted, defaults to the most recent year. |
| `period` | `string` |  | Fiscal period of the earnings call. When omitted, defaults to the most recent period. |

---

#### Paginate and sort Company Search Results for a given search id – `paginate_and_sort_search`

Fetch a page of results from an existing company search.

Use this after the initial search to page through results beyond the initial 
 limit, or to re-sort without re-running the search. Pass the search_id 
 returned by the initial search along with limit and offset. Only pass a 
 sort_field to re-sort; omit it and pagination keeps the search's default 
 (relevance) order.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `search_id` | `string` | *required* | UUID of an existing search, returned by search_companies |
| `offset` | `integer` | `0` | Number of results to skip (for pagination) |
| `limit` | `integer` | `50` | Maximum number of results to return, minimum is 10 |
| `sort_direction` | `string` |  | Sort direction: ASC or DESC. Defaults to ASC when sort_field is set. |
| `sort_field` | `integer` |  | idColumnType to sort by (e.g. 1 = Company, 10079 = Revenue). Omit to preserve the search's default (relevance) ordering. |

---

### Search Tools

Natural-language search across the CB Insights database.

#### Search Companies – `search_companies`

Find a population of companies matching criteria described in natural language. 
 Industry, market, and technology concepts are matched as keyterms; the attributes below 
 become structured filters. Returns filtered (not ranked) results, so ranking asks such as 
 "top 10 by revenue" come back unsorted — sort them yourself if order matters.

Use it for discovery: "AI drug discovery startups in Boston that raised a Series B", 
 "companies acquired by Walmart in logistics", "B2B SaaS companies with 20%+ headcount growth".

Do NOT use it to look up or verify one specific named company, or to check attributes of a 
 list of named companies ("Klarna", "AWS ProServe", "company named Evergrow", "are X, Y and Z 
 based in India") — those are rejected; use `get_company_profile` or another `get_company_*` 
 tool. Naming a company as a criterion is fine ("backed by Sequoia", "acquired by Walmart"). 
 For competitors of a named company prefer `get_company_competitors`; company search can be 
 used but is weaker for large multi-segment companies (Apple, ExxonMobil).

Available filter attributes (mention any of these in `query` and they are applied 
 automatically, as inclusions or exclusions): 
 geography (headquarters), business model (B2B, B2C, B2G, SaaS, marketplace, freemium, 
 usage-based, etc. — only when the query names one explicitly), company status, 
 commercial maturity, headcount, headcount growth 6m, headcount growth 12m, 
 headcount growth 24m, revenue, revenue growth latest, revenue growth future, 
 revenue multiple, revenue per headcount, stock price, market cap, mosaic overall, 
 mosaic momentum, mosaic money, mosaic market, mosaic management, M&A probability, 
 IPO probability, founded year, total funding, latest funding amount, latest valuation, 
 deal size, exit valuation, historical investment stages, funding round, funding date, 
 deal date, exit date, funding window, VC backed, analyst briefing, exit type, investor, 
 lead investor, acquirer, company name.

Caveats: 
 - Results may include some off-target companies — that is the nature of search over
  keyterm matching. Review the returned companies and drop rows that don't fit the
  intent before presenting them. Or run post processing logic to further filter or
  validate the list against additional custom filters. 
 - Geography is headquarters location only. There is no filter for operations, presence,
  expansion into, or adoption of something in a place, so such criteria go unsearched. 
 - Highly specific criteria — niche sub-sectors, several stacked quantitative constraints,
  obscure investor portfolios — can return very few or zero companies. When results are
  thin, drop or loosen the narrowest criteria, or split the query, instead of stacking more. 
 - Criteria are AND-combined. Genuinely alternative conditions ("funded OR acquired by X",
  "raised in the last 90 days OR grew headcount 20%+") need one search each. 
 - Prefer several narrow searches over one sprawling multi-sector search.

Always show the citation source URL in your answer - the results must be cited.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `query` | `string` | *required* | Describe the population of companies to find in natural language: the business they are in plus any attribute criteria (i.e. geography, funding, size, financials, investor, acquirer, status). Run one search per distinct vertical or theme — a query naming several unrelated sectors dilutes or drops some of them. Keep truly alternative conditions (A or B) in separate searches; everything in one query is combined with AND. Exclusions are supported: say what to exclude ("excluding wealth management firms"). |
| `limit` | `integer` | `50` | Maximum number of results to return, minimum is 25 |
| `extended_thinking` | `boolean` |  | Refine the filters against live search results before returning. Slower (allow a minute; the whole call is capped at 2 minutes) but more precise. Recommended when the query has exclusions or other negative constraints, or when precision matters more than latency. |

---

#### Search Deals – `search_deals`

Find funding deals (financing rounds and investments) matching criteria described in 
 natural language. Industry, market, and technology concepts are matched as keyterms; the 
 attributes below become structured filters. Each result is a deal: the company that raised, 
 the round, amount, date, and participating investors. Results are filtered, not ranked.

Use `search_companies` to get companies rather than individual rounds, `search_investors` 
 for a list of firms, and `search_partnerships` for non-financing deals (licensing, 
 partnerships, supply agreements). `search_companies` is also more effective in seeing which 
 companies a particular company invested in or acquired.

Available filter attributes (mention any of these in `query` and they are applied automatically): 
 geography, deal size, deal date, investment stage (funding round), investor, lead investor.

Caveats: 
 - Geography is the raising company's headquarters; there is no filter for where it operates. 
 - Anything outside the attribute list above (deal rationale, use of proceeds, valuation
  multiples) cannot be filtered on and goes unsearched. 
 - Highly specific criteria (a niche sub-sector plus a narrow date window plus a specific
  investor) can return very few or zero deals. When results are thin, loosen or drop the
  narrowest criteria rather than adding more.

Always show the citation source URL in your answer — the results must be cited.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `query` | `string` | *required* | Describe the funding deals to find in natural language: i.e. round/stage, deal size, date range, geography (company headquarters), and the investors or industries involved. Run one search per distinct sector or theme rather than naming many at once. Criteria are AND-combined, so run truly alternative conditions ("Series A or Series B led by X" where the sets differ) as separate searches. |
| `limit` | `integer` | `25` | Maximum number of results to return, minimum is 25 |

---

#### Search Investors – `search_investors`

Find a population of investors — venture capital firms (VCs), private equity funds (PE), 
 angel investors, family offices, corporate venture arms, hedge funds — matching criteria 
 described in natural language. Portfolio-company industry, market, and technology concepts 
 are matched as keyterms; the attributes below become structured filters. Each result is an 
 investor with their type, location, and investment activity. Results are filtered, not ranked.

Use `search_companies` to find the portfolio companies themselves, `search_deals` for 
 individual financing rounds, and `get_company_investors` / `get_company_profile` to look up 
 one named firm rather than discovering a set. A query that is just a firm's name, or a list of 
 named firms to check facts against, is rejected — name investors only as criteria 
 ("co-investors with Sequoia").

Available filter attributes (mention any of these in `query` and they are applied automatically): 
 investor name, investor geography, investor type, investor founded year, investment stage, 
 total funding, deal size, valuation, deal date, co-investor, deals last 12 months, total deals, 
 exit valuation, exits last 12 months, portfolio company name, portfolio company status, 
 portfolio company founded year, portfolio company location.

Caveats: 
 - Geography is headquarters location only; there is no filter for where a firm operates or
  is expanding. 
 - Highly specific criteria (narrow sub-sectors plus several stacked constraints) can return
  very few or zero investors. When results are thin, loosen or drop the narrowest criteria.

Always show the citation source URL in your answer — the results must be cited.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `query` | `string` | *required* | Describe the population of investors to find in natural language: type (i.e. VC, PE, angel, CVC, family office, hedge fund), location, investment stage and activity, and the portfolio companies or industries they back. Run one search per distinct sector or theme — naming several unrelated sectors dilutes them. |
| `limit` | `integer` | `25` | Maximum number of results to return, minimum is 25 |

---

#### Search Partnerships – `search_partnerships`

Find existing business relationships between companies — partnerships, alliances, 
 collaborations, vendor/client arrangements, licensing, supply/distribution, sponsorships — 
 matching criteria described in natural language. Results are filtered, not ranked.

Use it for: partnerships between two industries, cross-sector collaborations, vendor 
 relationships in a market, licensing deals, supply chain connections, sponsorships, 
 strategic alliances. Named companies are expected here as the partner sides.

Use `get_company_relationships` for every business connection of one named company without 
 criteria, `search_deals` for financing rounds, and `search_companies` for hypothetical 
 partners ("companies that could partner with X") — this tool only returns relationships 
 that already exist.

Relationship-level filters: relationship type (partnership, vendor/client, 
 licensor/licensee, supplier/distributor, sponsorship), relationship keywords, time period, 
 and one or two specific companies or described company populations as the partner sides.

When a partner side is described rather than named, it supports the full company filter set 
 (mention any of these in `query` and they are applied automatically): 
 geography (headquarters), business model (B2B, B2C, B2G, SaaS, marketplace, etc. — only when 
 named explicitly), company status, commercial maturity, headcount, headcount growth 6m, 
 headcount growth 12m, headcount growth 24m, revenue, revenue growth latest, 
 revenue growth future, revenue multiple, revenue per headcount, stock price, market cap, 
 mosaic overall, mosaic momentum, mosaic money, mosaic market, mosaic management, 
 M&A probability, IPO probability, founded year, total funding, latest funding amount, 
 latest valuation, deal size, exit valuation, historical investment stages, funding round, 
 funding date, deal date, exit date, funding window, VC backed, analyst briefing, exit type, 
 investor, lead investor, acquirer, company name.

Caveats: 
 - Geography is headquarters location only; there is no filter for where a company operates. 
 - Relationship coverage is sparser than company coverage: a specific relationship type plus
  a niche sector on both sides plus a short time window often returns very few or zero rows.
  When results are thin, widen the time period, drop the relationship type, or describe only
  one side.

Always show the citation source URL in your answer — the results must be cited.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `query` | `string` | *required* | Describe the business relationships to find in natural language: the relationship type, the activity or topic of the relationship, a time period, and the two partner sides — each either named companies or a described population ('healthcare companies'). Run one search per distinct relationship theme; criteria are AND-combined, so truly alternative conditions need separate searches. |
| `limit` | `integer` | `25` | Maximum number of results to return, minimum is 25 |

---

#### Search People – `search_people`

Find people (executives, founders, engineers, etc.) by their role and background. 
 Filters are extracted automatically from the natural-language query. Results are filtered, 
 not ranked.

Use it when the answer should be a list of PEOPLE ("Heads of Marketing at AI startups", 
 "ex-Salesforce executives now at seed-stage companies"). Use `search_companies` when the 
 answer should be COMPANIES, even if selected by their team ("which AI companies have 
 founders from Salesforce").

The search supports four optional, AND-combined sections: 
 - Person Details: name, location (the person's location), contact availability
  (email / LinkedIn), education degree, and leadership signals (below). 
 - Current Role: job title, seniority level, department, time in current role,
  plus the company/industry the role is at. 
 - Past Role: the same job attributes (no time-in-role) for a role the person
  previously held. 
 - Current or Past Role: a role the person holds OR has held.

Available leadership signals (career-spanning achievements; mention any in `query`): 
 repeat founder, technical founder, Y Combinator founder, gave an executive interview to 
 CB Insights, top university alum, founder money raised, valuation achieved, 
 revenue achieved, has IPO'd, has M&A'd, has acquired companies, investment stage 
 experience (Series A, B, C, etc.), and early employee at a top private or recently public company.

The company/industry side of any role reuses the full company filter set 
 (industry, market, technology, geography, headcount, revenue, funding, status, 
 etc.) — describe the company in natural language.

Available company filter attributes (mention any of these in `query` and they are applied automatically): 
 geography (headquarters), business model (B2B, B2C, B2G, SaaS, marketplace, etc. — only when 
 named explicitly), company status, commercial maturity, headcount, headcount growth 6m, 
 headcount growth 12m, headcount growth 24m, revenue, revenue growth latest, 
 revenue growth future, revenue multiple, revenue per headcount, stock price, market cap, 
 mosaic overall, mosaic momentum, mosaic money, mosaic market, mosaic management, 
 M&A probability, IPO probability, founded year, total funding, latest funding amount, 
 latest valuation, deal size, exit valuation, historical investment stages, funding round, funding date, 
 deal date, exit date, funding window, VC backed, analyst briefing, exit type, investor, 
 lead investor, acquirer, company name.

Each result is a person with their CB Insights profile URL (``profile_url``), 
 location, contact info, and roles (job title, seniority, tenure, plus a 
 ``company`` object carrying the org's name, ``id_org``, website ``url``, 
 ``logo_url``, and CBI ``profile_url``).

Caveats: 
 - Person location and company geography are headquarters/home locations, not where someone
  operates or is relocating to. 
 - Stacking a narrow job title, a niche company population, and a tight tenure window often
  returns very few or zero people. When results are thin, loosen the title or drop the
  narrowest constraint instead of adding more.

Always show the citation source URL in your answer — the results must be cited.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `query` | `string` | `` | Describe the people to find in natural language: role (job title, seniority, department, tenure), whether it is a current or past role, the company or company population the role is at, and personal attributes (name, location, contact availability, degree). Sections are AND-combined, so run genuinely alternative conditions as separate searches, and keep one distinct role or sector per search. |
| `limit` | `integer` | `25` | Maximum number of results to return, minimum is 25 |

---

#### Search Research – `search_research`

Find CB Insights proprietary research (analyst content) matching a topic and criteria 
 described in natural language. Topics, industries, and keywords are matched as keyterms; the 
 attributes below become structured filters. Results are filtered, not ranked.

Use it for analyst research only — for company, deal, or investor data use 
 `search_companies`, `search_deals`, or `search_investors` respectively.

Available filter attributes (mention any of these in `query` and they are applied automatically): 
 research topic / keywords, industry, specific organization, research type, publish date.

Research types: market maps, research briefs, state of reports, future of reports, 
 competitor analysis, top company lists, big tech reports, buyer perspective reports, 
 investment thesis maps, customer sentiment, webinars, markets.

Caveats: 
 - Without an explicit date in the query, results are limited to the last two years. 
 - Research coverage is a finite analyst library: a narrow topic combined with a specific
  research type, organization, and date window often returns very few or zero reports. When
  results are thin, broaden the topic or drop the research type rather than adding criteria.

Always show the citation source URL in your answer — the results must be cited.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `query` | `string` | *required* | Describe the research to find in natural language: topic or keywords, research type (e.g. market map, state of report), organizations covered, and publish-date range. State the date range explicitly when you want anything older than the last two years. Search one topic at a time; criteria are AND-combined. |
| `limit` | `integer` | `25` | Maximum number of results to return, minimum is 25 |

---

### Other Tools

#### Add Watchlist Column – `add_watchlist_column`

Add a custom column to a watchlist's table.

Returns the new column's `column_id` (use it, or the column name, with 
 set_watchlist_cell_values to fill in values). Type-specific arguments must 
 match `type` — passing `options` for a text column, say, is an error rather 
 than being ignored.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `name` | `string` | *required* | Name of the new column. |
| `type` | `string` | *required* | Column type: 'text', 'select' (a set of labeled options), 'number', or 'date'. Set cell values afterward with set_watchlist_cell_values. |
| `id_list` | `integer` |  | ID of the watchlist to add the column to (from get_watchlists). Provide this or list_name. |
| `list_name` | `string` |  | Name of the watchlist, matched case-insensitively; ambiguous or unknown names return alternates. |
| `options` | `array` |  | Only for a 'select' column: the option labels (required for select). |
| `number_format` | `string` |  | Only for a 'number' column: 'number' (default), 'currency', or 'percentage'. |
| `decimal_places` | `integer` |  | Only for a 'number' column: decimal places to display (0-20). |
| `date_format` | `string` |  | Only for a 'date' column: 'MM_DD_YYYY' (default, MM/DD/YYYY) or 'DD_MM_YYYY' (DD/MM/YYYY). Cell values are always entered as YYYY-MM-DD. |

---

#### Add Orgs To Watchlist – `add_watchlist_orgs`

Add organizations to an existing watchlist (by id_list or name).

Orgs already in the watchlist are effectively a no-op, and still come back 
 in `added`. Unresolved inputs (e.g. ambiguous names) come back in `errors` 
 and don't fail the rest. Resolved orgs that ListService's list-size cap 
 silently dropped come back in `not_added` instead of `added`, with a 
 `not_added_note` explaining it.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `selector` | `any` |  | Set of orgs to add to the watchlist. Accepts org_ids, org_names, competitors_of (ids or names), market_ids, and watchlist targeting (watchlist_ids, my_watchlists, my_competitors); the union is deduped. Every org the set resolves to is acted on — the set isn't capped. Inputs that don't resolve come back in `errors` without failing the rest. |
| `id_list` | `integer` |  | ID of the watchlist to add to (from get_watchlists). Provide this or list_name. |
| `list_name` | `string` |  | Name of the watchlist to add to, matched case-insensitively; ambiguous or unknown names return alternates. |

---

#### Create Watchlist – `create_watchlist`

Create a new custom watchlist for the current user, optionally seeded with 
 organizations.

The new watchlist is automatically pinned for the user.

Returns the new `id_list` and the orgs added; unresolved seed inputs (e.g. 
 ambiguous names) come back in `errors` without failing the creation. 
 Resolved seed orgs that ListService reported success for but didn't create 
 come back in `not_added` instead of `added`, with a `not_added_note` 
 explaining it.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `name` | `string` | *required* | Name for the new watchlist. |
| `selector` | `any` |  | Set of orgs to seed the new watchlist with. Accepts org_ids, org_names, competitors_of (ids or names), market_ids, and watchlist targeting (watchlist_ids, my_watchlists, my_competitors); the union is deduped. Every org the set resolves to is acted on — the set isn't capped. Inputs that don't resolve come back in `errors` without failing the rest. Omit to create an empty watchlist. |

---

#### Delete Watchlist – `delete_watchlist`

Delete a watchlist you own, or remove one that was shared with you.

What happens depends on whether you own the list, and the response says which 
 via `removed_for`: for a list you own it is deleted for everyone it was shared 
 with (`removed_for: "everyone"`); for a list shared with you it is removed from 
 your watchlists only and still exists for its owner (`removed_for: "you"`).

Requires the numeric id_list rather than a name, so a destructive call can't 
 hit the wrong watchlist via an ambiguous name. The id_list must be one of the 
 watchlists `get_watchlists` returns; the auto-generated competitors watchlist 
 can't be deleted.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `id_list` | `integer` | *required* | ID of the watchlist to remove (from get_watchlists). Required — this destructive action only accepts an id, not a name. |

---

#### Delete Watchlist Column – `delete_watchlist_column`

Delete a column (and its cell values) from a watchlist.

Works on any column the watchlist shows — the custom ones you added, the 
 built-in data columns, and the audit columns (Added On, Added By, Source). 
 The only exception is the company column, which identifies the rows.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `column` | `string` | *required* | Name of the column to delete (case-insensitive). |
| `id_list` | `integer` |  | ID of the watchlist (from get_watchlists). Provide this or list_name. |
| `list_name` | `string` |  | Name of the watchlist, matched case-insensitively; ambiguous or unknown names return alternates. |

---

#### Get Market – `get_market`

Returns an overview of a technology market or industry sector: market name, 
 description, and key features; the list of companies / competitors in the market 
 ranked by CBI Mosaic score (company health/momentum), each with CBI's scorecard 
 analysis (competitive analysis, customer outcomes, etc.); and market trends including 
 industry and sub-industry classification, equity funding totals and deal counts 
 over 1-year and 2-year windows, average Mosaic score, commercial maturity stage, 
 average employee headcount and headcount growth, a multi-year 
 equity-funding-and-deals time series, and recent exit activity (IPOs / acquisitions).

Use this to research a market's size, funding activity, competitive landscape, top 
 startups, and growth trends. Accepts either a known market id or a market name 
 (resolved against the CBI market taxonomy).

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `id_market` | `integer` |  | CBI market ID (if known). Provide this OR market_name. |
| `market_name` | `string` |  | A market name or description of a market (i.e. 'generative AI', 'digital lending'). Provide this OR id_market. |
| `max_companies` | `integer` |  | Maximum number of companies to return in the companies list. Defaults to 50 and is hard-capped at 100. |

---

#### Get MCP Usage – `get_usage`

Report how many CB Insights MCP tool calls the current user has made and 
 how many their plan allows.

Use this when asked about usage, remaining tool calls, quotas, limits, or 
 after a call is rejected for exceeding an allowance. Returns a daily 
 per-user figure and an annual figure for the user's team (or, for an account 
 with no team, an annual figure for the account itself), each with the number 
 of calls used, the limit, and the window it applies to.

---

#### Get Watchlist Contents – `get_watchlist_contents`

Fetch the organizations in a specific watchlist, by id_list or name.

The default 'orgs' preset returns lightweight org records (id_org, name, url, 
 status, latest funding) for the requested page plus the total member count. 
 The 'table' preset adds `columns` (the watchlist columns) and a `cells` map of 
 values per row. Pass the id_orgs to the `get_company_*` tools for full data.

Only approved members are returned — the same set the user sees when they 
 open the watchlist in the app. Both removed (rejected/deleted) entries and 
 pending suggestions (not yet approved or rejected) are excluded.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `id_list` | `integer` |  | ID of the watchlist to fetch (from `get_watchlists`). Provide this or `list_name`. |
| `list_name` | `string` |  | Name of the watchlist to fetch, matched against your watchlists (case-insensitive). Ambiguous or unknown names return alternates. |
| `preset` | `string` | `orgs` | 'orgs' (default) returns the member organizations. 'table' additionally includes each member's custom-column values (the watchlist's Notes, Funnel stage, etc.). |
| `limit` | `integer` | `25` | Max organizations (rows) to return (1-100). |
| `offset` | `integer` | `0` | Pagination offset over the members. |

---

#### Get Watchlists – `get_watchlists`

Return the current user's watchlists, selected by a ListSet.

Each watchlist comes back as {id_list, name, type (custom/competitors), 
 item_count, is_pinned, permission_level, can_rename}. With no selector (or an 
 empty one) this lists all of your watchlists; with containing_orgs it finds 
 which of your watchlists contain those orgs. Use a returned id_list with 
 `get_watchlist_contents` to see its members, or with the `get_company_*` 
 tools' `selector.watchlist_ids`.

`item_count` counts approved orgs, pending suggestions (not yet approved or 
 rejected), and non-org rows such as people — so it can be larger than 
 `get_watchlist_contents`'s `total` for the same watchlist, which counts 
 approved orgs only: the same set the user sees when they open the watchlist 
 in the app. Removed orgs count toward neither.

`permission_level` is your access to the list — owner for your own lists, 
 read_write or read for one shared with you. `can_rename` tells you whether 
 `rename_watchlist` will accept it: false for a read-only share and for the 
 auto-generated competitors list. The two `can_rename: false` cases differ for 
 membership edits, though: the competitors list still accepts 
 `add_watchlist_orgs` / `remove_watchlist_orgs`, but a read-only share 
 (`permission_level: "read"`) refuses those too — only `permission_level: 
 "read_write"` or `"owner"` can edit a list's members.

Unresolvable watchlist references (list_names, list_ids) or org references 
 (containing_orgs) are reported in `errors` with near-matches where available 
 and don't fail the rest. An id_list you don't own comes back as an error, not 
 as an empty result — so an empty `watchlists` with no `errors` genuinely means 
 the selection matched nothing.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `selector` | `any` |  | Which watchlists to return; dimensions are ORed. Accepts list_ids, list_names, my_watchlists, my_competitors, and containing_orgs (an OrgSet — return the watchlists containing any of those orgs). Omit or leave empty to get all of your watchlists. |

---

#### Remove Orgs From Watchlist – `remove_watchlist_orgs`

Remove organizations from a watchlist (by id_list or name).

Removal is a soft delete. Orgs that aren't approved members come back under 
 `not_found` (not an error) — including an org that's only a pending 
 suggestion on the watchlist, which no tool here can act on. Unresolved 
 inputs come back in `errors`.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `selector` | `any` |  | Set of orgs to remove from the watchlist. Accepts org_ids, org_names, competitors_of (ids or names), market_ids, and watchlist targeting (watchlist_ids, my_watchlists, my_competitors); the union is deduped. Every org the set resolves to is acted on — the set isn't capped. Inputs that don't resolve come back in `errors` without failing the rest. |
| `id_list` | `integer` |  | ID of the watchlist to remove from (from get_watchlists). Provide this or list_name. |
| `list_name` | `string` |  | Name of the watchlist to remove from, matched case-insensitively; ambiguous or unknown names return alternates. |

---

#### Rename Watchlist – `rename_watchlist`

Rename a watchlist (targeted by id_list or its current name).

Requires that you own the watchlist or hold write permission on it. The 
 auto-generated competitors watchlist can't be renamed.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `name` | `string` | *required* | New name for the watchlist. |
| `id_list` | `integer` |  | ID of the watchlist to rename (from get_watchlists). Provide this or list_name. |
| `list_name` | `string` |  | Current name of the watchlist to rename, matched case-insensitively; ambiguous or unknown names return alternates. |

---

#### Rename Watchlist Column – `rename_watchlist_column`

Rename a custom column on a watchlist (only columns you added).

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `column` | `string` | *required* | Current name of the custom column to rename (case-insensitive). |
| `new_name` | `string` | *required* | New name for the column. |
| `id_list` | `integer` |  | ID of the watchlist (from get_watchlists). Provide this or list_name. |
| `list_name` | `string` |  | Name of the watchlist, matched case-insensitively; ambiguous or unknown names return alternates. |

---

#### Set Watchlist Cell Values – `set_watchlist_cell_values`

Set values in a watchlist's custom columns for one or more orgs.

Unresolved orgs, orgs that aren't in the watchlist, unknown columns, values 
 that don't fit a column's type, and two keys landing on the same cell are 
 reported in `errors` (with alternates) and don't fail the rest. `set` lists 
 only what was written — trust it over assuming a value survived, since a 
 failure partway through a select column leaves that cell empty.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `values` | `object` | *required* | Values to set, keyed by org then column: {org: {column: value}}. The org key is a CBI entity id or a company name; the inner key is a custom column name. Value types: text→string, number→number, date→'YYYY-MM-DD', select→an option label (or list of labels), which replaces whatever was selected before. A null value clears the cell. One call can span multiple orgs and columns, up to 200 orgs and 1000 values (a list of select labels counts once per label) — split larger edits into several calls. Orgs must already be in the watchlist. Prefer entity ids over names: each distinct name costs a resolution, and two keys naming the same org conflict on the same cell. |
| `id_list` | `integer` |  | ID of the watchlist (from get_watchlists). Provide this or list_name. |
| `list_name` | `string` |  | Name of the watchlist, matched case-insensitively; ambiguous or unknown names return alternates. |

---


## Support

For questions or issues, contact [CB Insights support](https://www.cbinsights.com/contact).