How to connect Crunchbase MCP with Python

Answers a single analytical question about private-market data and returns structured tabular results (columns + rows). Read-only. Use this for analytical queries — aggregations, counts, rankings, comparisons, computed metrics, and trend analysis. For entity discovery (e.g. "find startups matching X criteria"), prefer ``cb_expert_build_search`` with ``preview_limit``. For profile details on a specific entity, prefer ``cb_expert_resolve_entity`` or ``cb_entity_get``. Each call answers exactly one question. Break multi-part questions into separate calls. Do NOT include "from Crunchbase" in the question text. Replace relative dates ("since Covid") with absolute dates ("since Dec 2019"). For detailed input guidelines and prompt patterns, call ``cb_reference('guidance/query_answer')``. Each profile entity in the results carries a ``url`` field — when presenting results to the user, render it as a markdown link ``[value](url)`` and never omit it. **Token cost:** for example, ~10,000 data tokens; scales with the data involved. Args: question: Natural language question/request to answer from Crunchbase data. Returns: Structured table results and associated metadata.

Finds Crunchbase entities matching natural-language criteria and returns a shareable crunchbase.com URL. When ``preview_limit`` is set, also returns matching entity data inline. Each profile entity in the results carries a ``url`` field — when presenting results to the user, render it as a markdown link ``[value](url)`` and never omit it. Use this for entity discovery and filtered lists — any request to find, browse, or filter entities matching criteria (e.g. "cybersecurity startups in the U.S. founded after 2021"). This tool is fast and optimized for this use case. Set ``preview_limit`` to return result data inline alongside the URL. For analytical queries that require computation (counts, rankings, aggregations), use ``cb_expert_query_answer`` instead. For detailed guidelines, call ``cb_reference('guidance/build_search')``. Input guidelines: - search_query must be non-empty and within the max length limit. - For date criteria, state absolute dates (e.g. "2021-01-01") rather than relative phrases like "recent" or "last 24 hours". Date fields such as announced_on resolve to whole calendar days, and a between range includes both endpoints. - Set preview_limit only if the user also wants result data alongside the URL. - Preview payloads can be very large token-wise; keep preview_limit small. - The maximum allowed preview_limit is caller-specific and based on current permissions. **Token cost:** for example, ~5,000 data tokens; scales with the data involved. Args: search_query: Natural-language description to compile into a search. preview_limit: Pass null or omit to skip preview, or a positive integer to request that many preview rows. Returns: Search URL, title, and optionally the first page of results.

Record user feedback on a previous ``cb_expert_query_answer`` result. After the user reviews a ``cb_expert_query_answer`` response, call this tool to capture their sentiment. Negative feedback may trigger the expert service to rewrite the query and return updated results. For feedback on a ``cb_expert_build_search`` result, use ``cb_expert_submit_search_feedback`` instead — this tool only accepts ``cb_expert_query_answer`` request ids. Args: subject_request_id: The ``request_id`` from a previous ``cb_expert_query_answer`` response. sentiment: One of ``"positive"`` (answer was helpful), ``"neutral"`` (answer was acceptable), or ``"negative"`` (answer was wrong or unhelpful). feedback: Optional free-text elaboration (max 1 000 characters). Returns: Feedback acceptance status and, when a rewrite is performed, the corrected result set.

Record user feedback on a previous ``cb_expert_build_search`` result. After the user reviews a ``cb_expert_build_search`` response, call this tool to capture their sentiment. Negative feedback may trigger the expert service to recompile the search and return a corrected one. Args: subject_request_id: The ``request_id`` from a previous ``cb_expert_build_search`` response. sentiment: One of ``"positive"`` (search was useful), ``"neutral"`` (acceptable), or ``"negative"`` (wrong or unhelpful). feedback: Optional free-text elaboration (max 1000 characters). Returns: Feedback acceptance status and, when a rewrite is performed, the corrected search.

Execute a structured entity search against the Crunchbase search API and return matching entities with their requested fields. Use this when you already have specific field IDs, operators, and values to filter on — for example after calling ``cb_reference`` or when the user provides explicit structured criteria. For natural-language entity discovery, prefer ``cb_expert_build_search`` which handles metadata resolution automatically. **Before calling this tool, resolve fields and operators via** ``cb_reference``: 1. ``cb_reference('entities')`` — discover searchable entity types and their ``collection_id`` values. 2. ``cb_reference('entities/<ed>/fields')`` — see available ``field_ids``, their ``field_type``, and whether they are sortable or filterable. 3. **REQUIRED for EVERY field used in a predicate or order clause:** ``cb_reference('entities/<ed>/fields/<field_id>')``. Do not guess operator_ids or values — this is the single most important call; it returns the valid operators, example predicate JSON, enum values, and live sample data for that field. See ``cb_reference('guidance/search_query')`` for why each step matters. **Predicate construction:** use ``predicates`` for simple flat filters or ``query`` for advanced searches with subqueries — the two are mutually exclusive. A minimal ``predicates`` filter:: predicates=[ {"field_id": "location_identifiers", "operator_id": "includes", "values": ["San Francisco"]}, {"field_id": "founded_on", "operator_id": "gte", "values": ["2020-01-01"]}, ] See ``cb_reference('guidance/search_query')`` for the ``query``/subquery form and exhaustive examples. **Error handling:** a validation error describes exactly what is wrong (invalid field_id, unsupported operator for field type, bad value format, etc.); use it to fix your search, consulting ``cb_reference('entities/<ed>/fields/<field_id>')`` for valid operators and example values. Each profile entity in the results carries a ``url`` field — when presenting results to the user, render it as a markdown link ``[value](url)`` and never omit it. **Token cost:** for example, ~2,000 data tokens; scales with the data involved. Args: collection_id: Entity collection to search (e.g. ``"organization.companies"``). Discover valid values from ``cb_reference('entities')``. An ``entity_def_id`` (e.g. ``"organization"``) is also accepted and transparently converted to the corresponding ``collection_id``. field_ids: Fields to include as columns in results. Defaults to the entity type's default search display columns. Discover valid values from ``cb_reference('entities/<ed>/fields')``. predicates: Simple flat predicates (field_id + operator_id + values). Mutually exclusive with ``query``. Each predicate corresponds to a single field filter. Consult ``cb_reference('entities/<ed>/fields/<field_id>')`` for valid operators and example values for each field. query: Full recursive query items for advanced searches including subqueries. Mutually exclusive with ``predicates``. Each item must include a ``type`` discriminator (``"predicate"`` or ``"sub_query"``). order: Sort clauses. Each must reference a field where ``is_sortable=true`` in the field metadata. limit: Maximum rows to return (min 1, default 20). Capped by caller permissions. after_id: Pagination cursor UUID — fetch the next page after this entity. Returns: Search results with count and entity data, or a detailed error describing what needs to be fixed.

Resolve a company, investor, person, or other entity name to a canonical Crunchbase entity. Disambiguates a named entity reference against the Crunchbase catalog. When a single confident match is found it is returned directly; otherwise a ranked candidate list is returned for the caller to choose from. **Token cost:** for example, ~5,000 data tokens; scales with the data involved. Args: name: Entity name to disambiguate (1--100 characters). collection_id: Crunchbase entity collection to search within. Any valid Crunchbase collection identifier is accepted — common examples: ``"organizations"``, ``"people"``, ``"principal.investors"`` (organizations + people who are investors). An ``entity_def_id`` (e.g. ``"organization"``) is also accepted and transparently converted. Omitting it with ``domains`` searches organizations; otherwise it searches organizations and people together. Pass an explicit collection when the entity type is known. domains: Websites, as either a bare domain or a full URL — both ``["acme.com"]`` and ``["https://www.acme.com/about"]`` work, and only the host is used for lookup. **Strongly preferred when resolving a company** — domain lookup takes precedence over name-based autocomplete matching and is significantly more accurate. An explicit collection must expose a searchable ``website_url`` or the request is rejected with an actionable error. Do not supply a company's domain when resolving a person — that searches for the company and returns it instead, and a personal profile URL resolves the site's owner rather than the person (``linkedin.com/in/someone`` returns LinkedIn). context: Free-text background that helps the disambiguation model pick the right candidate (max 10,000 characters). Supply any information available about what the user was doing when the tool was invoked — for example the surrounding conversation, the industry or geography under discussion, or other entities already mentioned. The more situational detail provided, the better the service can rank ambiguous matches. cb_entity_get: Controls automatic entity profile retrieval when a match is found. Enabled with default settings when omitted. Pass null to disable, or an object to customize which fields, cards, and related-entity limit the embedded profile uses. When enabled and a match is returned, the entity profile is fetched automatically and included in "entity". Returns: Disambiguation result — either a single match or ranked candidates. When ``cb_entity_get`` is enabled and a match is found, the ``entity`` field contains the full entity profile.

Retrieve the full Crunchbase profile for an entity, including financial history, leadership, locations, industry categories, and related entities. Returns a structured profile with labeled fields and cards, using display metadata from the Crunchbase metadata service. Use this when the user wants detailed information about a specific, already-identified entity — not for fanning out across many entities; use ``cb_expert_build_search`` or ``cb_search_query`` when the user wants multiple entities. On a followup call to drill into specific data from an initial ``cb_entity_get``, pass ``card_ids`` to focus the ``related_entity_limit`` budget entirely on the cards of interest, and ``field_ids=[]`` to skip top-level fields and save tokens. **Card pagination:** When a lookup card has more entities than fit in a single response, ``has_more_entities`` is ``True``. To fetch the next page, call again with the same ``entity_id`` and ``entity_def_id`` as the profile you are paginating, ``card_ids`` set to the single card you want to paginate, ``field_ids=[]`` to skip top-level fields, and ``after_id`` set to the cursor of the last entity in that card's ``entities``: take that entity's ``properties`` item whose ``field_id`` is ``identifier`` and read ``value.uuid``. A card whose lookup grants ``is_limit_overridable`` pages at ``related_entity_limit``, capped at 100 entities per request and bounded by your ``max_lookup_limit`` permission; a card that denies it pages at that card's own ``lookup.limit`` instead, which on many cards is far smaller than the budget — read a whole relationship of that kind with ``cb_search_query`` or ``cb_expert_build_search`` rather than paging it. Stop when ``has_more_entities`` is ``False``; an exhausted card comes back with an empty ``entities`` list, which is the end of the pages and not an error. **Token cost:** for example, ~1,000 data tokens; scales with the data involved. Args: entity_id: UUID or permalink of the entity to look up. Must be a real, known identifier — **never guess or fabricate**. Use ``cb_entity_autocomplete`` to obtain a valid identifier when you don't already have one. entity_def_id: Entity type (e.g. ``"organization"``, ``"person"``, ``"funding_round"``). Defaults to ``"organization"`` when omitted. Must be specified for non-organization entities — **do not guess**; use the ``entity_def_id`` from the identifier that provided the entity_id. A ``collection_id`` (e.g. ``"organizations"``) is also accepted and transparently converted. related_entity_limit: Maximum total related entities across all lookup cards. Defaults to 100, maximum 2000. The budget is distributed evenly across the selected cards, and a card whose lookup denies ``is_limit_overridable`` returns at most its own ``lookup.limit`` — on many cards far smaller than that share — however large the share is. This whole-response reading holds while ``after_id`` is unset; with ``after_id`` set the value is the page size for the single card named in ``card_ids``. field_ids: Specific field IDs to include in the response. Defaults to all selectable fields when omitted or null. Pass ``[]`` to skip top-level fields entirely (saves tokens on followup calls). Values are intersected with selectable fields. card_ids: Specific card IDs to include in the response. Defaults to one card per related collection when omitted or null — name a card here to retrieve one the default response leaves out. When specified, the ``related_entity_limit`` budget is fully dedicated to the listed cards. after_id: Pagination cursor — the ``value.uuid`` of the ``identifier`` property on the last entity of the previous page (``entities[-1].properties`` item with ``field_id == "identifier"``). Fetches the next page of entities for the specified card. Requires exactly one ``card_ids`` entry. Returns: Entity profile with properties and cards.

Search for Crunchbase entities by name. Returns matching entities (organizations, people, funding rounds, etc.) based on the provided query string. Use this to find entity identifiers before passing them to other tools. **Token cost:** for example, ~200 data tokens; scales with the data involved. Args: query: Value to perform the autocomplete search with. collection_ids: Comma-separated list of collection ids to search against. Leave blank to search all identifiers. ``entity_def_id`` values (e.g. ``"organization"``) are also accepted and transparently converted to the corresponding ``collection_id``. limit: Number of results to retrieve (default 10, max 25). Returns: Matching autocomplete entities with identifiers, facet ids, and short descriptions.

Ask a natural-language question about the Crunchbase data domain — what entities, fields, and relationships exist — or assess whether a draft question is answerable. **Before using this tool, consider these alternatives:** - Prefer `cb_reference('entities')` for structured schema lookups (entity list, field catalogs, card definitions, field types) when you already know which entity or area to inspect. It gives precise, structured answers without a round-trip to the expert service. - Prefer `cb_expert_query_answer` when the question can be answered by *the data itself* (e.g. "how many Series-B rounds happened in 2024?"). This tool is for *meta-questions* about the shape of the domain, not for querying actual records. Use this tool when you don't know where to start or want to ask a natural-language question about what the Crunchbase domain covers. It supports two intents: **discover** (default) - Browse the data catalog without a question. Returns a domain map of entities and fields, suggested analytical paths, and example questions you can ask. Optionally narrow with focus tokens (e.g. ["funding", "biotech"]). **assess** - Evaluate a draft question before executing it. Returns diagnostics on whether the question is answerable, what clarifications might improve it, and recommended reformulations. Requires the question parameter. **Token cost:** for example, ~100 data tokens; scales with the data involved. Args: intent: "discover" to browse the domain catalog, "assess" to evaluate a draft question. Defaults to "discover". question: Natural-language question to assess. Required for "assess" intent, optional for "discover". focus: Optional list of focus tokens to narrow scope (e.g. ["funding", "biotech"]). Maximum 10 items. max_suggestions: Maximum number of suggestions to return (1-5). Defaults to 5. Returns: Domain exploration results including matched concepts, domain map, suggested paths, diagnostics, and recommended questions.

Answer a question about the Crunchbase product, platform, pricing, or data coverage. This tool answers meta-questions about Crunchbase itself: product features, pricing plans, data methodology, coverage, integrations, account management, billing, API docs, and platform capabilities. It does not query Crunchbase entity data or return market intelligence results. Use `cb_knowledge_center` when the user asks what Crunchbase can do, what it covers, how to use it, or whether it supports something. Do not answer those questions from general model knowledge. **Token cost:** for example, ~250 data tokens; scales with the data involved. Args: question: The user's question about the Crunchbase product, platform, pricing, data coverage, integrations, API docs, or account topics. Maximum 1000 characters. Returns: A Knowledge Center response with a grounded answer and citation sources.

Look up Crunchbase schema reference and tool usage guidance by path. Call with an empty path (or ``"index"``) to get the full navigable index — every top-level section available to you, its bare path, and a one-line description. Every response also lists the paths you can drill into next; copy them verbatim rather than constructing your own. Top-level sections: - ``field_types`` / ``field_types/<field_type_id>`` — field-type and operator reference. - ``operators`` — generic operator and predicate reference. - ``entities`` / ``entities/<entity_def_id>`` / ``entities/<entity_def_id>/fields`` / ``entities/<entity_def_id>/fields/<field_id>`` / ``entities/<entity_def_id>/cards`` — browse searchable entity types, their fields (with live sample data and predicate examples for a single field), and relationship cards. - ``guidance/query_answer`` / ``guidance/build_search`` / ``guidance/search_query`` — detailed usage guides for the corresponding tools. Any guide is readable directly; the index lists a guide only when you're entitled to use its tool. Example paths: ``entities/organization``, ``entities/organization/fields/name``, ``field_types/text_short``. An unrecognized or malformed path never errors — it returns the index plus a closest-match hint. **Token cost:** free. Args: path: Reference path to look up. Empty string returns the index. Returns: Markdown content for the requested path.

Returns the current user's data token allowance (limit, used, available, status, and when it resets). A DATA_TOKENS_EXHAUSTED failure from another tool usually reports this allowance in its error's `exhausted_meters`; use this when it is absent or to re-check it later (for example after the reset time). Other metering or access errors are not reported here. **Token cost:** free.