add_companies_to_list
ChatGPTAdds a hand-picked set of companies to an existing list. ⚠️ Side-effectful — mutates a saved list. Confirm before calling. Provide the list_uid (from get_my_lists/create_list) and company_uids when you have them, or domains if that's all you have (exactly one of the two; domains are resolved server-side, so no need to chain lookup_companies first). Maximum 500 items per request. Trigger on "add these to my … list", "put company X on list Y". To take companies off a list, use remove_companies_from_list. For specific, individually chosen companies only — send ALL curated UIDs/domains in ONE call. Never walk a paginated search adding page by page; results WILL be silently incomplete. To save an entire search or similar-companies result set, use `add_search_results_to_list` instead. Returns the updated list size; UIDs/domains that did not resolve are echoed in unresolved_company_uids/unresolved_domains. Resolve a company or list name to its UID first. Pairs with create_list (make → populate) and sync_list_to_crm (populate → push).
add_search_results_to_list
ChatGPTAdds EVERY company matching a search to a list, server-side, in one call. ⚠️ Side-effectful — mutates a saved list. Confirm before calling. Use this instead of paging search results into add_companies_to_list: the backend enumerates the full result set itself, so nothing is lost to pagination. Trigger on "save all results to a list", "add everything matching … to my list", "add these similar companies to a list". To remove every match instead, use remove_search_results_from_list. Inputs: list_uid plus the search — EITHER the same typed filter kwargs as ai_search_companies (keywords_include, locations, employees_min, …), OR filters = the filters_used dict returned by a prior search (don't mix flat keys into it), OR similar_to_company_uids (up to 10 seed companies — each a UID, or a domain if that's what you have — combinable with typed kwargs) for a similarity-based add. Optional deselected_company_uids (UIDs; domains also accepted) excludes specific companies ("all except these"); expected_count (the total from the prior search, minus any deselected_company_uids) lets the backend cross-check the match; a mismatch is rejected. At least one real constraint is required — match-everything requests are refused. Small result sets apply immediately (companies_added + new list size returned). Large ones (≥1,000 matches) run as a background job: the response carries update_id — poll get_list_add_status(list_uid=…, update_id=…) until it completes. matched_count is approximate for similarity-seeded searches; post-add counts are authoritative.
ai_search_companies
ChatGPTSubmit the user's request and return a paginated list of matching companies (name, domain, description, HQ, revenue, employee estimate, ownership, funding, profile_url). Extras like naics, linkedin, or contact fields are available via the fields argument. When summary-first rows are active, rows after the top 5 are id/name/domain stubs (plus profile_url) — expand via enrich_companies/get_company or re-run with fields. FIRST CALL: pass `query` ONLY. Put every constraint (location, headcount, revenue, industry, etc.) into the query string in plain language. Do NOT set structured parameters (locations, employees_*, revenue_*, keywords_*, …) on the first call; the tool extracts these from the query itself. Optional follow-up: if results are too broad, add structured filter parameters on a later call to narrow — not required on every search. For the next page, repeat the same query and filters, increment page, and pass the prior response's search_after; never bulk-fetch pages. If results are thin, broaden the query or filters and use the relevant *_include_unknown option. Use in_crm to filter CRM membership instead of calling get_crm_link for every row. For European company searches or market-size queries use search_legal_entities. Also, for names with European legal-form suffixes such as AB, GmbH, SARL, BV, Oy, ApS, Ltd, SA, or other European suffixes, or prompts about filings, registration numbers, official financial statements, officers, key people, ownership, or group/corporate structure, use search_legal_entities. Resolve a company name with lookup_companies; for companies like X, use find_similar_companies.
create_list
ChatGPTCreates a new (empty) company list. ⚠️ Side-effectful — creates persistent state. Confirm intent with the user before calling. Required: name. Optional visibility: "private" (default; for anything the user calls personal/"just for me"), "team", or "organization". No name de-duplication: two calls with the same name make two distinct lists, so on any transient/ambiguous error check get_my_lists before retrying — do not blindly re-call. After creation, populate with add_companies_to_list (the new list's id is in the response). Typical flow: ai_search_companies → create_list → add_companies_to_list.
enrich_companies
ChatGPT*Batch profile enrichment — the go-to when you have a set of companies. Pass `company_uids` when you have them, or `domains` if that's all you have (exactly one of the two; max 10 per call) and get consolidated profiles back, each echoing its `input` value and including a `url` to the full Grata profile. Set `include_contacts=true` to bundle executive contacts. Why pick this over `get_company`:* it handles many companies in one call (and takes raw domains directly when you don't have UIDs). Heavy nested collections (locations, investors, conferences, contacts) are capped per-company with a total/_total count when truncated — point the user to the company's url for the uncapped data. A company entry may carry withheld_fields naming fields the user's plan does not include — those come back empty for a plan reason, not because the company has no such records, so say the plan doesn't cover them rather than stating the company has none, and don't retry. For >10 items, split into batches of 10 and merge. For one company where you already hold the UID and want the light profile, get_company is the leaner choice (less payload).
export_search_results
ChatGPTGenerates a downloadable .xlsx of company search results. ⚠️ Side-effectful — creates a file and runs an async job. Hard 4-step workflow, no shortcuts: (1) call preview_export_cost with the same filters; (2) show the user cost + current balance + remaining-after; (3) get an explicit "yes"/"go ahead" after showing the preview; (4) only then call this with confirm=True. Consent is required on every call, including 0-credit/free accounts — never infer consent from the earlier search request, and never skip the ask. Use the typed kwargs mirroring ai_search_companies (for locations/locations_exclude pass a country's ISO code — UK→"GB", Mexico→"MX" — not the spelled-out name; spell out a whole US state ("California")), or pass a prior search's filters dict (don't mix flat keys into it). To export a `find_similar_companies` result set, pass the same `company_uid`/`company_uids` seed(s) you gave that tool (each a UID, or a domain if that's what you have; with the same filters) so the file reproduces the ranked similarity set instead of a broader filter-only search; use the identical seed + filters you passed to preview_export_cost. Returns file_id + a _web_url to Grata's My Files page; after submitting, tell the user the credits used and estimated remaining (from the preview), then poll get_export_status(file_id=…) for the download link.
fetch_legal_entity_document
ChatGPTRetrieve a temporary download URL for a completed request (status Done). Returns download_url and expires_at. Present download_url to the user as a clickable link; do not open or download it on the user's behalf. If it expires, call this tool again with the same IDs to get a new link at no additional document-order token cost. Use list_legal_entity_document_requests to check the status of a Processing request.
find_similar_companies
ChatGPT"Find companies like X" (and like Y and Z). Given 1–10 seed companies, return new companies that resemble them. Trigger on "similar to", "competitors of", "comps for" (when the user means look-alikes, not public-market comps), or any list of example companies used as a template. Inputs: seeds as company_uid/company_uids — each a Grata UID (a company domain like 'stripe.com' also works if that's what you have; up to 10). If the user gives names, resolve each to a handle with lookup_companies first; the legacy company_name param is rejected at runtime. Seeds are excluded from the results by design — don't promise the user their own seeds back; enrich those separately via get_company/enrich_companies. Narrowing: accepts the full ai_search_companies filter set (locations, industries, revenue/employees/funding ranges, ownership_types, business_models, year_founded, keywords, lists, *_include_unknown) applied on top of similarity; unresolved names fail loud the same way ai_search_companies does. keyword_match (core default / mentioned) sets the keyword match depth exactly as in ai_search_companies. For ownership_types, pass the convenience value private to match every non-public type at once (expands to the eight non-public tokens), or list granular tokens (ib_pe_backed, pe_add_on, public, …). location_types picks which of a company's location records the geography must match — hq (default), lob, op, esthq, estloc; pass all five to include all non-headquarter locations. For locations/locations_exclude, pass a country's 2-letter ISO code (United Kingdom→GB, Mexico→MX), not the spelled-out name; US states are not ISO codes — spell out "California" or use "City, ST". Past ~5 seeds the per-seed signal dilutes. Pagination: page_size is fixed at 25; page is capped at 100. Not for public-market valuation comps — that's get_public_comps.
get_active_mandate
ChatGPTFull detail for one active mandate, by deal_id (obtained from search_active_mandates). Returns the same fields as a search row but with the complete additional_details write-up (the long deal narrative is truncated in search results), advisor block, and full contact details. Use when the user wants to drill into a specific mandate surfaced by search_active_mandates. Requires a deal_id — there's no name lookup; run search_active_mandates first to get one.
get_banker_by_id
ChatGPTSingle banker (M&A advisor / intermediary) firm profile by Grata `company_uid`. Resolve a UID with search_bankers or lookup_companies first. Returned fields: - Firmographic: name, domain, firm_type, firm_role, description, city, country, greater_regions, linkedin, primary_phone, primary_email, year_founded, employees, estimated_revenue_usd - Coverage: When firm_profiles enrichment is missing, the payload includes coverage_note. Relay that note. Missing ltm_deals / nl_summary are not zero activity and must not be invented. Search-card ltm_advised_deal_count / total_advised_deal_count may still be present — report them if present. Principal / acquisition counts (total_deal_count / ltm_deal_count) are not on this profile. When coverage_note is absent, deal-activity fields come from firm_profiles. - Deal counts — three distinct windows, never substitute one for another: total_advised_deal_count (all-time advisory), ltm_advised_deal_count (trailing 12 months — use for "how active is this advisor?"), ytd_deal_count (calendar year-to-date, counted from announcement dates in ltm_deals — not a separately role-scoped counter). YTD is always ≤ LTM, and is legitimately much smaller than LTM early in a calendar year. Report the window the user asked for and label it explicitly. A null ytd_deal_count means it could not be derived — say so rather than reporting LTM as YTD. Principal / acquisition counts (total_deal_count / ltm_deal_count) are not on this profile — use get_buyer_by_id / search_buyers when the user wants buy-side activity for the same firm. - Deal size range: avg_deal_value and median_deal_value (USD); deal_value_p25 / deal_value_p75 are the role-scoped disclosed-value percentiles and primary_side is buy or sell. Per-deal values are in ltm_deals[] (same rows as advised_deals[]). - Sector breakdown: top_sectors — array of {grata_title, count, dealmakers[]}, sorted by deal count descending. Use count for sector concentration. - Buy-side vs sell-side split: total_buy_side_advised_parties and total_sell_side_advised_parties — the sides of the deals this firm advised on: buy side = it advised the acquirer, sell side = it advised the seller. Use their ratio for "is this advisor more buy-side or sell-side?". Deals where the firm acted on its own account (e.g. its own bolt-on acquisition) are excluded; for those use get_buyer_by_id. - Timeline: first_deal_date, most_recent_deal_date - Recent deals (LTM): ltm_deals — each entry has {deal_title, announcement_date, deal_value, transaction_type, sectors[], principals[{name, principal_type}], dealmakers[{full_name, ml_user_id, current_seniority, transaction_role}], dealmaker_attribution}. principals are deal-party companies (buyer/seller/banker firms), not people. Per-deal people: when dealmaker_attribution is available, dealmakers lists the named individuals attributed to that transaction. When it is unavailable, dealmakers is empty — do not invent names from active_deal_team or top_sectors[].dealmakers. Use get_banker_person only when the user wants that person's full deal history. Never count these entries to state how many deals a firm has done in any window — use total_advised_deal_count / ltm_advised_deal_count / ytd_deal_count. - Deal team / top advisors: active_deal_team — array of {full_name, current_seniority}, the firm's current dealmakers (use this for "top advisors at <firm>" and to check whether a named person is currently at the firm). Names and seniority only; no email, phone, or LinkedIn per individual contact. When coverage_note is absent, an empty or omitted list means no bankers are linked yet — say so rather than rendering an empty table. For deal-team contact details, search search_active_mandates for active mandates with advisor filter. - Freshness: is_stale (bool) — true when most_recent_deal_date is older than 12 months. No last_verified_at timestamp or `data_c…
get_banker_person
ChatGPTDealmaker-network profile for one banker/professional by `person_id`. person_id is the MergerLinks ml_user_id from search_banker_people. Use after search_banker_people when the user wants deal history, principals, or sector detail. Returned fields: identity (first_name, last_name, seniority/speciality), current firm (company_name, company_uid, firm_role), deal totals (lifetime_deal_count, value range, first/last deal dates), top_sectors / top_regions, and a recent sample of deals (capped for context size — use lifetime_deal_count for how many deals the person has overall, not len(deals)).
get_buyer_by_id
ChatGPTSingle buyer (PE firm / strategic / VC / family office) profile by Grata `company_uid`. Resolve a UID with search_buyers or lookup_companies first. Returned fields: - Firmographic: name, domain, firm_type, firm_role, description, city, country, greater_regions, linkedin, primary_phone, primary_email, year_founded, employees, estimated_revenue_usd - Coverage: When firm_profiles enrichment is missing, the payload includes coverage_note. Relay that note. Missing ltm_deals / nl_summary are not zero activity and must not be invented. Search-card ltm_deal_count / total_deal_count may still be present — report them if present. When coverage_note is absent, deal-activity fields come from firm_profiles. - Preferred check size (deal size range): target_equity_cheque_down and target_equity_cheque_up (integers in fund_currency, defaulting to USD when fund_currency is null — the firm's stated investment range). May be null if the firm has not disclosed criteria. - Deal counts — three distinct windows, never substitute one for another: total_deal_count (all-time principal / acquisition), ltm_deal_count (trailing 12 months — use for "how active is this buyer?"), ytd_deal_count (calendar year-to-date, counted from announcement dates in ltm_deals — not a separately role-scoped counter). YTD is always ≤ LTM, and is legitimately much smaller than LTM early in a calendar year. Report the window the user asked for and label it explicitly. A null ytd_deal_count means it could not be derived — say so rather than reporting LTM as YTD. Advisory / banker counts are not on this profile — use get_banker_by_id / search_bankers when the user wants advised-deal activity for the same firm. - Deal size statistics: avg_deal_value and median_deal_value (USD, based on historical closed deals). deal_value_p25 / deal_value_p75 are the role-scoped percentiles and primary_side is buy or sell. Acquisition history is acquisition_deals[] (same rows as ltm_deals[]). - Sector breakdown: top_sectors — array of {grata_title, count, dealmakers[]}, sorted by deal count descending. Use count for sector concentration. Sector dealmakers are people active in that sector (top 5 sectors only), not a per-deal lead list. - Portfolio / investment activity: buy_side_principal_count and sell_side_principal_count; ltm_deals — each entry has {deal_title, announcement_date, deal_value, transaction_type, sectors[], principals[{name, principal_type}], dealmakers[{full_name, ml_user_id, current_seniority, transaction_role}], dealmaker_attribution}. principals are deal-party companies, not people. Per-deal people: when dealmaker_attribution is available, dealmakers lists the named individuals attributed to that transaction. When it is unavailable, dealmakers is empty — do not invent names from active_deal_team or top_sectors[].dealmakers. Never count ltm_deals entries to state deal activity — use total_deal_count / ltm_deal_count / ytd_deal_count. For the firm's full portfolio / complete acquisition history, use search_transactions(buyer_companies=[company_uid]) (or get_company_acquisitions for a strategic's own purchases). - Timeline: first_deal_date, most_recent_deal_date - Deal team contacts: active_deal_team — array of {full_name, current_seniority}. Names and seniority only; no email, phone, or LinkedIn per individual contact. When coverage_note is absent, an empty or omitted list means no deal team members are linked yet — say so rather than rendering an empty table. - Freshness: is_stale (bool) — true when most_recent_deal_date is older than 12 months. No last_verified_at timestamp or data_confidence score is available; is_stale is the only freshness signal. - AI narrative: nl_summary (auto-generated firm summary) Access: requires Dealmaker Profiles entitlement. Returns 403 if not entitled.
get_companies_in_list
ChatGPTReturn the companies inside a known list (free), by list_id. Trigger on "what's in list X", "show me the companies on my … list", "which companies in my list have high seller intent". Output is the same company shape as ai_search_companies, paginated 25/page with a search_after cursor. For extras like naics, linkedin, or contact fields use enrich_companies or get_company. When summary-first rows are active, rows after the top 5 are id/name/domain stubs (plus profile_url) — expand them with enrich_companies (batch, up to 10 per call); this tool has no fields argument, so there is no uniform-full-row re-run. Seller Intent filter: pass seller_intent_levels (e.g. ["high_intent"] or ["High Intent"]). Also available on ai_search_companies. CRM membership filter: pass in_crm="only" to keep just the companies on this list that are already matched to a record in the org's CRM, or "exclude" for the ones that are not — use it for "which of these are already in our CRM" rather than calling get_crm_link per company. To rank conferences by CRM overlap, call this once per conference UID with in_crm="only" and compare the returned count. Conferences are lists too: for a conference's "attendees / exhibitors / speakers / sponsors / the list", pass the conference's UID here. Resolve names to a list_id first — get_my_lists or search_list_library for regular lists, search_conferences or get_saved_conferences for events. Requires the UID — it does not accept a list name.
get_company
ChatGPTThe standard single-company profile fetch. Given one company_uid, returns the core profile: description, HQ, year founded, ownership/funding stage, revenue (TTM, USD), Grata + LinkedIn employee estimates and YoY growth, business models, NAICS, latest funding summary, keywords, social links, seller-intent score, and profile_url. This is the right default when the user asks "tell me about company X" or "get company X". Requires a UID — resolve a name with lookup_companies first. Pick the right neighbor: use enrich_companies instead when you have several companies or only domains (no UIDs), or need locations/investors/conferences/contacts bundled in. Use get_company_financials/_funding_rounds/_investors/_acquisitions for deep single-topic detail. This tool returns the headline seller_intent_score; use get_company_seller_intent for sub-scores, topics, and month-over-month trends, and get_company_exit_readiness for the underlying exit-readiness signal breakdown (time_since_funding, time_since_acquisition, founder_signal). This tool is the lightweight all-rounder. Dealmaker firms: for an M&A advisor / banker / advisory firm, prefer search_bankers enriched rows (deal counts, sector concentration, deal-size range, deal team) when present; for a PE firm / strategic / VC / family-office buyer, prefer search_buyers enriched rows the same way. Fall back to this generic profile when enrichment is absent.
get_company_acquisitions
ChatGPT*What a company has acquired** (it as buyer), by `company_uid`. Each row: acquired company (name + UID), date, `acquisition_value`/`enterprise_value` (often null), `type` (e.g. "Corp"), `post_evaluation`, target employee estimate, banks/advisors, multiples, and sources. Trigger on "X's acquisitions", "companies X has bought", "X's M&A history". Paginated. This is company-scoped buyer history; for cross-market deal search use `search_transactions`, and for live* sale mandates use search_active_mandates.
get_company_contacts
ChatGPTGet people/contacts at one or more companies. Trigger on "who's the CEO/CFO of X", "decision-makers at X", "contact info for X's execs", "get me emails at these companies". Required: company_uids — each a Grata UID (a company domain like 'stripe.com' also works when you don't have the UID) — a non-empty list; resolve names via lookup_companies. Returns per contact: name, current_title/normalized_current_title, work_email, link_linkedin, verified_email.state (e.g. "Deliverable"/"Unknown"), seniority, location, and is_executive. Each company carries profile_url, the Grata company profile where the full contact details are shown. `contact_type`: "execs" (executives only), "user" (contacts you've added), "all" (both; the default if omitted). list_id scopes to contacts within a saved list. Filters: has_email / has_linkedin (booleans — keep only contacts with a work email, or a LinkedIn URL). email_status (list; any of deliverable, risky, unknown, undeliverable, pending) keeps only contacts whose work-email verification is in those states. departments (list) accepts only "exec" (executives) or numeric position IDs — it is NOT a free-text department search, so pass ["exec"] to narrow to executives. query is a free-text match over contact name, company name, work email, and title. Sorting: sort_field one of company, department, recency, has_email; sort_direction asc or desc (both must be supplied together to take effect). Handle the data responsibly: results include real work emails. Many rows have blank emails; don't present those as contactable.
get_company_exit_readiness
ChatGPTExit readiness signal breakdown for one `company_uid`. Returns three signals: time_since_funding (funding recency / "no recent funding"), time_since_acquisition (hold-period / transaction timing), and founder_signal (founder-age signal). Each signal includes a value (positive, negative, neutral, or null) plus supporting metadata — years and date on funding/acquisition signals, age on founder signal, and is_strategic on acquisition when applicable. When a company was acquired, the acquisition signal takes precedence and the funding signal may be suppressed. `founder_signal` age fields: - age — estimated founder age in years (integer), or null when no qualifying founder age is available. - age_decade — MCP-only decade label matching the Exit Readiness UI (e.g. "50s", "60s"), derived as floor(age / 10) * 10 + "s". Absent when age is null. Use this to prioritize or filter by age band (e.g. late-career founders in their 60s/70s). Example when age data exists: ``json {"founder_signal": {"value": "positive", "age": 62, "age_decade": "60s"}} ` **Requires a UID** — resolve a name with lookup_companies first. **Pair with get_company:** get_company returns the headline seller_intent_score; this tool returns the underlying signals and **does not** include seller intent score. **403:** requires the org's package to include Exit Readiness Signals (Feature.EXIT_READINESS_SIGNALS). Search filters use different token names (funding_signal, transaction_signal, founder_age_signal`); this tool returns API field names above.
get_company_financials
ChatGPTRevenue detail for one company, by company_uid. Returns TTM revenue with multi-currency conversions (USD, EUR, GBP, SEK, NOK, DKK), a revenue_display_type (e.g. "public" vs estimated), reconciliation figures, and — for private companies — estimate factors/filings (these come back null for large public companies, as seen for Apple). Use when the user asks specifically about revenue/financials beyond the headline number in get_company. Not for valuation multiples or peer benchmarking — use get_public_comps.
get_company_funding_rounds
ChatGPTRound-by-round funding history for one company_uid. Each row: date, deal_amount (USD), deal_type (e.g. "Seed VC - II"), valuation (often null), and the participating investors (each with name, UID, domain, lead flag) plus any banks/sources. Trigger on "how was X funded", "X's funding rounds", "who led X's Series B". Paginated (count, pages). Sibling split: get_company_investors aggregates by investor across rounds; this tool lists the rounds themselves.
get_company_investors
ChatGPTThe investor roster for one `company_uid`, aggregated per investor. Each row: investor name + UID, investor_type, number_of_rounds they joined, and participating_rounds (round, lead flag, date). Trigger on "who invested in X", "X's backers/investors". Use get_company_funding_rounds instead when the user wants the rounds/amounts/valuations timeline rather than the deduplicated investor list.
get_company_legal_entities
ChatGPTGet the registered legal entities of a Grata company by company_uid. Use this when the user starts from a company (name, domain or UID) and asks for its registry financials, shareholders, officers or group structure: pass the returned legal_company_id values to get_legal_entities or get_legal_entity_relations. For the corporate group, if get_company_legal_entity_group_structure is in your tool list, call it with a returned legal_company_id. If it is not listed, call get_legal_entity_group_structure with that legal_company_id. Each entity carries its country, registration number and flags: is_canonical (the company's main entity), is_canonical_in_country (the main entity in its country) and is_servable (its financial statements may be shown). An empty list means the company has no registry match.
get_company_legal_entity_group_structure
ChatGPTGet the corporate group for one registry entity. legal_company_id comes from get_company_legal_entities. Returns the ultimate parent, companies, parent/child relations, and is_oversized, member_count and relation_count from the group structure row. An oversized group has empty companies and relations and still returns the counts. There is no company match check. Always reads the exported dataset.
get_company_mcp_usage
ChatGPTPer-teammate breakdown of MCP token usage across the org (free), for last week/month/year. Trigger on "who's using Grata MCP the most", "how is our MCP usage split across the team". Returns one row per teammate (sorted by yearly usage, zero-usage users shown as 0.0) plus an org total row; each value is that user's share of the org's total token allocation (0.12 = 12%). This is the MCP slice of the org's single token pool, cut by teammate; for the overall balance (all consumption) use get_token_usage. When the allocation is waived, percentages are null and only the waived flag is meaningful.
get_company_seller_intent
ChatGPTSeller Intent detail for one `company_uid`. Returns month-over-month seller intent history: composite seller_intent_score per calculation_date, so you can chart trends over time. Component sub-scores and topics (M&A, VDR, Advisory, Financial Sponsor, Investment Bank) are not exposed through this tool. Requires a UID — resolve a name with lookup_companies first. Pair with `get_company`: get_company returns only the latest headline seller_intent_score; this tool returns the full historical trend. Time window: optional months (2, 4, 6, 12, 18, or 24; default 2 — past two months). 403 / visibility: requires the org's package to include Seller Intent (Feature.SELLER_INTENT, Alpha). Orgs without that package do not see this tool and cannot call it. Trial-limited orgs that do have access may receive zeroed scores for the most recent 12 months.
get_contacts_in_list
ChatGPTReturn paginated contacts from a saved list by list_id. Trigger on "contacts in list X", "who are the execs on my … list", "emails for companies in this list". Required: list_id (Grata list UID — resolve names via get_my_lists or search_list_library first). Returns a flat paginated page of contact records (results, count, page, pages, next, previous). Each contact includes name, current_title, work_email, link_linkedin, verified_email.state, seniority, location, company, and is_executive. _web_url opens the list's contacts page in Grata, where the full contact details are shown. `contact_type`: "execs" (executives only), "user" (contacts you've added/unlocked), "all" (both; default). Pagination: page (default 1), page_size (default 25, max 100). Large lists can have thousands of contacts — paginate rather than requesting everything at once. When to use which tool: prefer this for list-scoped contact workflows (one call, server-side pagination). Use get_company_contacts when you already have specific company_uids and need per-company grouping or filter/sort params (has_email, query, departments, etc.). Handle the data responsibly: results include real work emails. Many rows have blank emails; don't present those as contactable.
get_crm_link
ChatGPTGet the CRM record URL for an already-synced company, by company_uid — a Grata UID (a company domain like 'stripe.com' also works if that's what you have). Returns crm_link (a direct deep link to the record in the CRM) and crm_name (e.g. "HubSpot", "Salesforce"). Trigger on "where is X in our CRM", "link to X's CRM record". If the company hasn't been synced yet, returns synced: false with no crm_link — offer sync_company_to_crm (with confirmation). Present crm_link to the user as a clickable link; do not try to fetch it yourself.
get_export_status
ChatGPTPoll an in-flight export and retrieve its download link, by file_id (from export_search_results). Statuses: Pending/Processing (not ready — wait a few seconds and re-poll), Complete (a download_url is returned), Failed (errored — offer to retry), Stuck (pending >10 min — suggest support/retry). When `Complete`, present `download_url` to the user as a clickable link — do NOT fetch/curl it yourself. The link is a presigned S3 URL meant for the user's browser; sandboxed tools will fail on it, and the link is regenerated on each call, so just re-poll if it expires. Only meaningful after an export has been submitted.
get_filing_date_formula
ChatGPTReturns a ready-to-paste =GRATA.FILING_DATE(...) formula string (or a candidates list when the company is ambiguous) for one company × field × date. The evaluated cell is the filing date of the most recently reported period for that field as of the date argument — not a financial value. Use this ONLY when the deliverable is an Excel file — either the user is working in the Grata Excel add-in, OR has asked from any surface (including chat) for an .xlsx of public comps — and you need a filing-date DATE column. For metric VALUE columns use get_public_financials_formula; for period-end columns use get_period_end_formula. For inline content (markdown tables, analysis, Q&A in conversation) use get_public_comps instead, which returns VALUES — never paste raw =GRATA.FILING_DATE(...) strings into chat text, where they cannot evaluate, and do not invent filing dates inline (get_public_comps has no filing_date JSON fields). Requires the Comps feature (matches the Grata web app and Excel add-in). It is included by default in the Scale and Alpha packages, and lower-tier packages can have it enabled too (add-on, per-org grant, or trial) — so do NOT assume a package tier. Callers without the Comps feature receive a feature_not_in_package error naming the required feature; retrying won't change the result. Why this tool: you pass structured params and get back a formula whose field name and date the server has checked and whose ticker it resolved — never construct or string-stitch a GRATA.FILING_DATE formula, ticker, or exchange suffix yourself. It does not check that Grata has data for that combination. Parameters: - company: a flexible identifier — Grata UID, ticker (with or without :EXCHANGE), domain, or company name. Natural-language names resolve via the same search that backs the add-in's 'Find Company'. - field: the exact field name (case-insensitive) — one of the strings below. A near-miss returns an error listing valid entries, so fix it, do not guess. The field selects which metric's reporting period to date (same catalog as GRATA.PUBF). Share Price returns the unadjusted EOD closing price; Share Price Adj returns EOD adjusted_close (split-and-dividend-adjusted). Field catalog: - Valuation: Share Price (unadjusted closing price), Share Price Adj (split-and-dividend-adjusted close), Outstanding Shares, Market Cap, Enterprise Value, EV/Rev (LTM), EV/EBITDA (LTM), EV/EBIT (LTM), EV/Gross Profit (LTM), Price/Earnings Ratio, EV/Rev (FY1), EV/EBITDA (FY1), EV/Rev (FY2), EV/EBITDA (FY2) - Income Statement: Revenue (LTM), EBITDA (LTM), EBITDA Margin (LTM), Gross Profit (LTM), Gross Margin (LTM), EBIT (LTM), EBIT Margin (LTM), Quarterly Revenue, Qtr Rev Growth (YoY), Qtr Earnings Growth (YoY), Tax Rate (LTM), Revenue (FY1), EBITDA (FY1), Revenue (FY2), EBITDA (FY2) - Balance Sheet: Net Debt, Debt/Equity Ratio - Cash Flow: Operating Cash Flow Margin (LTM), Free Cash Flow Margin (LTM) Forward period semantics — pick the suffix to match the column header, not the calendar year alone: - (LTM) fields (e.g. Revenue (LTM), EV/EBITDA (LTM)) = trailing twelve months ending on the date argument; use for the most recently reported period (e.g. CY2025A as of a March 2026 anchor). - (FY1) fields (e.g. Revenue (FY1), EV/Rev (FY1)) = first annual fiscal year-end in Earnings.Trend after the period end of the most recent filing available as of the date argument (not the raw calendar date). FILING_DATE itself returns no filing for projections. Use when the column is labeled like "2026P" or "next FY revenue". - (FY2) fields (e.g. Revenue (FY2), EV/Rev (FY2)) = the second annual fiscal year-end after that same last-filed period end (the year after FY1); use when the column is labeled like "2027P" or you need one year beyond (FY1). Legacy names such as Revenue (+0Y) and Revenue (+1Y) are accepted and normalized to Revenue (FY1) and Revenue (FY2). - date: an "MM/DD/YYYY" string anchoring the as-of window (e.g. "2/15/2026") — the same window GRATA.PUBF uses. Must fall between 1/1/2020 and today (data is unavailable before 2020 and for future dates); an out…
get_legal_entities
ChatGPTGet full legal entity profiles and detailed financial statements by legal_company_ids from search_legal_entities lookup. At least one legal_company_id must be supplied. At most 10 can be requested per call. Use financial_statement_year_range to restrict returned financial statement columns to an inclusive [min, max] year window of at most five years; omit it to return the latest five available reporting years.
get_legal_entity_group_structure
ChatGPTGet the legal registry group structure for a legal entity by legal_company_id from search_legal_entities. Returns the ultimate parent, the companies in the group, and parent/child ownership. Draw ownership_stake, or max_ownership_stake when ownership_stake is absent. Empty companies and relations means there is no structure to draw. A company_count and no companies or relations means the group exists but is too large to draw. This is not the Grata-enhanced group graph; that graph will be get_grata_enhanced_group_structure.
get_legal_entity_minority_ownership
ChatGPTGet the minority ownership above a legal entity. legal_company_id comes from search_legal_entities or get_company_legal_entities. Returns owners (companies and people, no minimum stake), owner-to-owned relations, and ultimate owners. This is not the subsidiary group graph; use get_legal_entity_group_structure for that graph. Draw ownership_stake, or max_ownership_stake when ownership_stake is absent. Empty owners and relations means there is no structure to draw. is_oversized, or a note with no owners or relations, means the graph exists but is too large to draw; the counts are complete. truncated_direct_owner_count is direct owners omitted upstream, not an incomplete total.
get_legal_entity_relations
ChatGPTGet ownership and people relationships for a legal entity by legal_company_id from search_legal_entities lookup. Use this after finding a legal entity to understand related owners, shareholders, officers, beneficial owners, entity-structure owners, and key-person roles. Use include_history=True to include historical officer/key-person records. Defaults to false to avoid unwanted data.
get_list_add_status
ChatGPTPoll a large list update started by `add_search_results_to_list` or `remove_search_results_from_list`, by list_uid + update_id. Statuses: processing (not done — wait a few seconds and re-poll), complete, failed (the job errored — offer to retry with the tool the response names), stuck (processing >10 min — suggest the same retry or contacting support). When an add is complete, compare companies_added with the matched_count from the submit response: a lower number usually means some matches were already in the list or the add reached the plan's list-size limit — tell the user the actual added count rather than reporting a plain success. When a remove is complete, report the new list_company_count.
get_mcp_tool_costs
ChatGPTReturns the per-tool token figures for the MCP server, as a tool_costs map of tool name → value per call. Trigger only when the user explicitly asks about this (e.g. "which Grata tools are free") or to compare tools before running them. 0 means always callable even at 100% of allocation. This tool itself is free, so checking costs is always safe. Tools absent from the map are unmapped on the backend (treated as billable).
get_my_lists
ChatGPTList the user's saved company lists (free). Trigger on "my lists", "lists I created", "lists shared with me", "find my HVAC list". Returns each list's id (needed for get_companies_in_list), name, company_count, visibility, folder, and is_mine. `scope`: "all" (default: own + shared-by-me + shared-with-me), "mine" (everything I created, any visibility — use for "lists I created/own"), "user" (my private only), "shared" (I shared into org), "org" (teammates shared with me). Optional query text filter and sort_by (updated_on default, created_on, name, company_count, user_follows). This covers the user's own/org lists only; for the public marketplace use search_list_library. The result set can be very large — filter with query rather than paginating blindly, and resolve a named list to its id here before calling get_companies_in_list.
get_period_end_formula
ChatGPTReturns a ready-to-paste =GRATA.PERIOD_END(...) formula string (or a candidates list when the company is ambiguous) for one company × field × date. The evaluated cell is the fiscal period-end date of the most recently reported period for that field as of the date argument — not a financial value. Use this ONLY when the deliverable is an Excel file — either the user is working in the Grata Excel add-in, OR has asked from any surface (including chat) for an .xlsx of public comps — and you need a period-end DATE column. For metric VALUE columns use get_public_financials_formula; for filing-date columns use get_filing_date_formula. For inline content (markdown tables, analysis, Q&A in conversation) use get_public_comps instead, which returns VALUES — never paste raw =GRATA.PERIOD_END(...) strings into chat text, where they cannot evaluate, and do not invent period-end dates inline (get_public_comps has no period_end JSON fields). Requires the Comps feature (matches the Grata web app and Excel add-in). It is included by default in the Scale and Alpha packages, and lower-tier packages can have it enabled too (add-on, per-org grant, or trial) — so do NOT assume a package tier. Callers without the Comps feature receive a feature_not_in_package error naming the required feature; retrying won't change the result. Why this tool: you pass structured params and get back a formula whose field name and date the server has checked and whose ticker it resolved — never construct or string-stitch a GRATA.PERIOD_END formula, ticker, or exchange suffix yourself. It does not check that Grata has data for that combination. Parameters: - company: a flexible identifier — Grata UID, ticker (with or without :EXCHANGE), domain, or company name. Natural-language names resolve via the same search that backs the add-in's 'Find Company'. - field: the exact field name (case-insensitive) — one of the strings below. A near-miss returns an error listing valid entries, so fix it, do not guess. The field selects which metric's reporting period to date (same catalog as GRATA.PUBF). Share Price returns the unadjusted EOD closing price; Share Price Adj returns EOD adjusted_close (split-and-dividend-adjusted). Field catalog: - Valuation: Share Price (unadjusted closing price), Share Price Adj (split-and-dividend-adjusted close), Outstanding Shares, Market Cap, Enterprise Value, EV/Rev (LTM), EV/EBITDA (LTM), EV/EBIT (LTM), EV/Gross Profit (LTM), Price/Earnings Ratio, EV/Rev (FY1), EV/EBITDA (FY1), EV/Rev (FY2), EV/EBITDA (FY2) - Income Statement: Revenue (LTM), EBITDA (LTM), EBITDA Margin (LTM), Gross Profit (LTM), Gross Margin (LTM), EBIT (LTM), EBIT Margin (LTM), Quarterly Revenue, Qtr Rev Growth (YoY), Qtr Earnings Growth (YoY), Tax Rate (LTM), Revenue (FY1), EBITDA (FY1), Revenue (FY2), EBITDA (FY2) - Balance Sheet: Net Debt, Debt/Equity Ratio - Cash Flow: Operating Cash Flow Margin (LTM), Free Cash Flow Margin (LTM) Forward period semantics — pick the suffix to match the column header, not the calendar year alone: - (LTM) fields (e.g. Revenue (LTM), EV/EBITDA (LTM)) = trailing twelve months ending on the date argument; use for the most recently reported period (e.g. CY2025A as of a March 2026 anchor). - (FY1) fields (e.g. Revenue (FY1), EV/Rev (FY1)) = first annual fiscal year-end in Earnings.Trend after the period end of the most recent filing available as of the date argument (not the raw calendar date). Companies with different fiscal calendars (e.g. WMT Jan 31 vs AMZN Dec 31) get different FY1 period ends for the same input date. An input date between a period close and its filing date uses the prior filing, not the unfiled period. Use when the column is labeled like "2026P" or "next FY revenue". - (FY2) fields (e.g. Revenue (FY2), EV/Rev (FY2)) = the second annual fiscal year-end after that same last-filed period end (the year after FY1); use when the column is labeled like "2027P" or you need one year beyond (FY1). Legacy names such as Revenue (+0Y) and Revenue (+1Y) are accepted and normalized to Revenue (FY1) and Revenue (FY2). - date: an "MM/DD/Y…
get_private_market_indices
ChatGPTReturns sector-level Private Market Index (PMI) metrics derived from aggregate, anonymized virtual data-room behavior. Use this tool when the user wants a sector-wide metric, trend, ranking, comparison, momentum, or change over time. It measures deal activity, buyer activity, and buyer commitment. It does not return named deals, businesses for sale, potential buyers, completed transactions, valuations, or raw deal-room counts. Routing guard: Do not infer PMI intent from generic phrases such as 'M&A activity', 'deal activity', 'deal volume', 'deal supply', 'open deals', 'live deals', 'buyer interest', or 'buyers active'. These phrases are ambiguous unless the user asks for an aggregate or sector-level metric, score, trend, momentum, ranking, or comparison. Ask what result they want before calling a tool. Depending on the query, the plausible choices may be sector-wide PMI metrics, named businesses currently marketed for sale, named potential buyers, or completed transactions. Clear PMI requests include: 'Is software M&A activity increasing or decreasing?', 'Compare healthcare and software PMI scores', 'Rank industries by buyer activity score', 'Show the three-month buyer commitment trend for fintech', and 'How does software's aggregate deal activity compare with the market?' Metrics: - Deal activity score: normalized active deal-room count (deal volume/supply); higher means more open rooms. pct_deal_share is the sector's percentage of all deal rooms. - Buyer activity score: relative number of distinct buyers looking in the sector (breadth); higher means more buyers. pct_buyer_share is the sector's percentage of all buyers. - Buyer commitment score: percentage (0-100) of sector buyers seriously engaging with deals (depth); higher means deeper engagement. Data begins 2025-10-01; coverage_start/coverage_end show availability. - Momentum: change versus baseline for intervals through window_length (7d, 1mo, 3mo, 6mo, 1y, 2y, 3y, YTD). Activity data begins 2023-01-01; unavailable baselines are omitted. - Target size (target_size): the sector's employee-headcount mix among companies behind its current deal-room activity, as a bucket→percentage map. Buckets: 1-50=SMB, 51-250=Middle Market, 251-5000=Upper Middle Market, 5000+=Enterprise, Unknown=headcount not available. Percentages sum to ~100. Omitted when no headcount data is available for the sector. Metrics include start/end, annual_volatility, and available momentum windows. Specific-sector results also include min/max extrema; broad scans and market comparisons do not. Compare deal activity score, buyer activity score, and buyer commitment score because they can diverge. For industries requests, uncovered codes appear in insufficient_data_naics_codes (too little coverage) or unknown_naics_codes (no PMI data found). Mixed requests return covered results plus these lists; a request fails only when no code is covered.
get_public_comps
ChatGPTReturns public comparables with valuation multiples, operating metrics, and aggregate statistics (min, max, mean, median). Default output is VALUES — use this for analysis, Q&A, markdown tables, and any inline (non-file) deliverable. Inline VALUES use the same engine as GRATA.PUBF: the same (ticker, field, date) is the same number, stored at warehouse four-decimal ratio scale (e.g. 11.8476 — present those digits; do not round multiples to one decimal in chat tables). For chat comps tables, as-of history, and multi-year trends, call this tool (one as_of per call) and answer with a markdown table of VALUES. Do not call get_public_financials_formula, get_period_end_formula, or get_filing_date_formula, and do not offer to create an Excel file, unless the user asked for an .xlsx. Requires the Comps feature (matches the Grata web app and Excel add-in). It is included by default in the Scale and Alpha packages, and lower-tier packages can have it enabled too (add-on, per-org grant, or trial) — so do NOT assume a package tier. Callers without the Comps feature receive a feature_not_in_package error naming the required feature; retrying won't change the result. Pass the company's company_uid — a Grata UID (a company domain like 'stripe.com' also works if that's what you have); use lookup_companies first if you only have a name. Optional as_of is an LTM-anchor date as MM/DD/YYYY. Omit it (or pass today) for current snapshot values. A historical date re-evaluates every row through the same engine as GRATA.PUBF for that date, then recomputes stats. Dates before 1/1/2020 or after today return DATE_OUT_OF_RANGE — tell the user there is no data; do not invent numbers. This tool accepts at most one as_of per call — there is no dates[]. A multi-year trend in chat is N calls (one date each), answered as a markdown table of VALUES; do not create an Excel file unless the user asked for one, and do not paste GRATA.PUBF strings in chat. To target calendar year YYYY, pass 2/15 of YYYY+1 (after that year's close, before the next quarter reports): CY2020 → 2/15/2021 … CY2024 → 2/15/2025. Each returned company includes a pubf_ticker field already formatted as TICKER:EXCHANGE (e.g. "MSFT:NASDAQ") — use it verbatim; never guess a ticker symbol or exchange suffix. Inline VALUES include LTM metrics, market-data fields (share_price, share_price_adj, outstanding_shares — the same engine as GRATA.PUBF Share Price / Share Price Adj / Outstanding Shares, including today), and forward (FY1 / FY2) fields in the JSON (e.g. revenue_0y, revenue_1y, ebitda_0y, ebitda_1y, ev_over_rev_0y, ev_over_rev_1y, ev_over_ebitda_0yr, ev_over_ebitda_1yr). Use the returned keys for inline tables — do not guess or invent alternate field names. In GRATA.PUBF / GRATA.PERIOD_END, (FY1) / (FY2) anchor to the last filing available as of the date argument (period end of that filing, then the next two annual Trend dates) — not the raw calendar date. This JSON has no period_end or filing_date value fields — do not invent those dates inline. === For Excel-file deliverables (opt-in) === If the deliverable is an Excel file — whether the user is working directly in the Excel add-in OR has asked from any surface (including chat) for an .xlsx to be created — construct GRATA.PUBF / GRATA.PERIOD_END / GRATA.FILING_DATE formulas from the conventions below so the file is live and refreshable when opened. If the deliverable is inline (markdown table, analysis, Q&A in conversation), return values directly — do NOT output raw GRATA.PUBF, GRATA.PERIOD_END, or GRATA.FILING_DATE strings in chat text, where they cannot evaluate. The trigger is "an Excel file is being produced," not "the user is in the add-in." Prefer the dedicated get_public_financials_formula tool to obtain each formula: it returns a ready-to-paste GRATA.PUBF string with a checked field and date (and resolves company names to the right TICKER:EXCHANGE) so you never string-stitch a ticker, field, or date yourself. For inline chat tables, use the JSON forward keys above (revenue_0y, revenue_1y, etc.); for Excel fil…
get_public_financials_formula
ChatGPTReturns a ready-to-paste Excel formula, =GRATA.PUBF(...), that looks up one public-company financial figure (a valuation, income-statement, balance-sheet or cash-flow metric) in Grata's public financials for one company × field × date, or a candidates list when the company is ambiguous. Use this ONLY when the deliverable is an Excel file — either the user is working in the Grata Excel add-in, OR has asked from any surface (including chat) for an .xlsx of public comps. For inline content (markdown tables, analysis, Q&A in conversation) use get_public_comps instead, which returns VALUES (including revenue_0y, revenue_1y, and related forward keys) — never paste raw =GRATA.PUBF(...) strings into chat text, where they cannot evaluate. Requires the Comps feature (matches the Grata web app and Excel add-in). It is included by default in the Scale and Alpha packages, and lower-tier packages can have it enabled too (add-on, per-org grant, or trial) — so do NOT assume a package tier. Callers without the Comps feature receive a feature_not_in_package error naming the required feature; retrying won't change the result. Why this tool: you pass structured params and get back a formula whose field name and date the server has checked and whose ticker it resolved — never construct or string-stitch a GRATA.PUBF formula, ticker, or exchange suffix yourself. It does not check that Grata has data for that combination. Parameters: - company: a flexible identifier — Grata UID, ticker (with or without :EXCHANGE or .EXCHANGE), domain, or company name. Natural-language names resolve via the same search that backs the add-in's 'Find Company'. - field: the exact field name (case-insensitive) — one of the strings below. A near-miss returns an error listing valid entries, so fix it, do not guess. Share Price returns the unadjusted EOD closing price; Share Price Adj returns EOD adjusted_close (split-and-dividend-adjusted). Field catalog: - Valuation: Share Price (unadjusted closing price), Share Price Adj (split-and-dividend-adjusted close), Outstanding Shares, Market Cap, Enterprise Value, EV/Rev (LTM), EV/EBITDA (LTM), EV/EBIT (LTM), EV/Gross Profit (LTM), Price/Earnings Ratio, EV/Rev (FY1), EV/EBITDA (FY1), EV/Rev (FY2), EV/EBITDA (FY2) - Income Statement: Revenue (LTM), EBITDA (LTM), EBITDA Margin (LTM), Gross Profit (LTM), Gross Margin (LTM), EBIT (LTM), EBIT Margin (LTM), Quarterly Revenue, Qtr Rev Growth (YoY), Qtr Earnings Growth (YoY), Tax Rate (LTM), Revenue (FY1), EBITDA (FY1), Revenue (FY2), EBITDA (FY2) - Balance Sheet: Net Debt, Debt/Equity Ratio - Cash Flow: Operating Cash Flow Margin (LTM), Free Cash Flow Margin (LTM) Forward period semantics — pick the suffix to match the column header, not the calendar year alone: - (LTM) fields (e.g. Revenue (LTM), EV/EBITDA (LTM)) = trailing twelve months ending on the date argument; use for the most recently reported period (e.g. CY2025A as of a March 2026 anchor). - (FY1) fields (e.g. Revenue (FY1), EV/Rev (FY1)) = first annual fiscal year-end in Earnings.Trend after the period end of the most recent filing available as of the date argument (not the raw calendar date). Companies with different fiscal calendars (e.g. WMT Jan 31 vs AMZN Dec 31) get different FY1 period ends for the same input date. An input date between a period close and its filing date uses the prior filing, not the unfiled period. Use when the column is labeled like "2026P" or "next FY revenue". - (FY2) fields (e.g. Revenue (FY2), EV/Rev (FY2)) = the second annual fiscal year-end after that same last-filed period end (the year after FY1); use when the column is labeled like "2027P" or you need one year beyond (FY1). Legacy names such as Revenue (+0Y) and Revenue (+1Y) are accepted and normalized to Revenue (FY1) and Revenue (FY2). - date: an "MM/DD/YYYY" string anchoring the GRATA.PUBF LTM window (e.g. "2/15/2026"). Must fall between 1/1/2020 and today (data is unavailable before 2020 and for future dates); an out-of-range date returns an error. Returns — unambiguous input (UID, full TICKER:EXCHANGE / TICKER.EXCHANGE, or exac…
get_saved_conferences
ChatGPTThe conferences the user has saved/followed (their "Your Saved Conferences" panel). Trigger on "my saved conferences", "events I'm following". Returns event details including each conference UID and source_link (the conference's own official/external website; may be blank). To list the companies attending a saved conference, pass its UID to `get_companies_in_list` (conferences are lists). For discovering new events the user hasn't saved, use search_conferences.
get_token_usage
ChatGPTThe org's token balance (free) — the single pool drained by exports, CRM uploads, and MCP calls. Returns total, used, remaining, percent_used/percent_remaining, a waived flag (true = unlimited, percentages null), and token_period_end_date — when the current token period ends. Trigger on "how many tokens do we have left", "are we near our limit". For a per-teammate breakdown of how that consumption splits across the team (the MCP portion), use get_company_mcp_usage — same pool, different cut.
list_legal_entity_document_requests
ChatGPTList this organization's document download requests for a legal entity, most recent first. Includes in-flight (Processing), completed (Done), and failed requests for any teammate in the organization. Use it to check an existing request's status. When status is Done, call fetch_legal_entity_document with request_id.
list_legal_entity_documents
ChatGPTList official source documents available for download for a legal entity (including annual reports, interim reports, and other registry filings). Use after resolving legal_company_id via search_legal_entities or get_legal_entities. Returns document_id, document_name, document_type, document_period, and token_cost. This tool only lists documents; it does not place an order. First step before request_legal_entity_document. Pagination: page defaults to 1 and page_size defaults to 20.
logout
ChatGPTLog out of the Grata MCP server (free). Immediately revokes the access token used for this session so it can no longer call any tool — use when you're finished, or if the token may be compromised. Only affects the current OAuth session's token; other sessions and Grata API keys are unaffected.
lookup_companies
ChatGPTResolve a specific organization identity from a company name, domain, ticker, or registration number. Returns score-ranked company and legal-entity candidates; rank 0 is the best match. Read entity_type before using a result: a company has its company UID in id, while a legal entity has its internal identifier in data.legal_company_id and its id is not a company UID. Expect homonyms and disambiguate using the type-specific data. This tool resolves a known identity; it does not discover, paginate, or find similar sets of organizations.
preview_export_cost
ChatGPTStep 1 of every export — preview the credit cost (free, no side effects). Always call this before export_search_results, using the same filters as the search the user wants to export. Returns cost, credits_available, credits_after_export, overage, can_afford, a human-readable message, and filters_used (the resolved filter dict you can hand straight to the export call). Then: show the user all three numbers (cost / current balance / remaining-after) and get an explicit "yes" — consent is required even when `cost` is 0 (an export still creates a file and runs a job). Build filters with the typed kwargs that mirror ai_search_companies (keywords_include, revenue_min, name_contains, …; for locations/locations_exclude pass a country's ISO code (UK→"GB", Mexico→"MX"), not the spelled-out name; spell out a whole US state ("California")); as an escape hatch you may pass a prior search's filters dict via filters, but never mix flat keys into that dict (the backend rejects it). Exporting a `find_similar_companies` result set? Pass the same seed you gave that tool — company_uid (single) or company_uids (list), each a UID (a domain also works if that's what you have) — alongside the same filters. This reproduces the ranked similarity set; omitting the seed silently previews a broader filter-only search (more rows, including off-target matches).
remove_companies_from_list
ChatGPTRemoves a hand-picked set of companies from an existing list. ⚠️ Destructive — deletes entries from a saved list. Confirm before calling. Provide the list_uid (from get_my_lists) and company_uids when you have them, or domains if that's all you have (exactly one of the two; domains are resolved server-side). Maximum 500 items per request. Trigger on "remove Z from the list", "take X off my list". To remove every company matching a search, use remove_search_results_from_list instead. Returns the updated list size — report that; the backend does not count how many companies were actually taken off the list. UIDs/domains that did not resolve are echoed in unresolved_company_uids/unresolved_domains. Resolve a company or list name to its UID first.
remove_search_results_from_list
ChatGPTRemoves EVERY company matching a search from a list, server-side, in one call. ⚠️ Destructive — deletes entries from a saved list. Confirm before calling. Trigger on "remove everything matching … from my list", "take all the <segment> companies off the list". To remove specific companies by UID or domain, use remove_companies_from_list instead. Inputs: list_uid plus the search — EITHER the same typed filter kwargs as ai_search_companies, OR filters = the filters_used dict returned by a prior search (don't mix flat keys into it), OR similar_to_company_uids (up to 10 seed companies — each a UID or a domain — combinable with typed kwargs). Optional deselected_company_uids (UIDs; domains also accepted) keeps specific matches on the list ("all except these"); expected_count (the total from the prior search, minus any deselected_company_uids) lets the backend cross-check the match; a mismatch is rejected. At least one real constraint is required — match-everything requests are refused. Small result sets apply immediately and return the new list size; report that, since the backend does not count how many companies were actually taken off the list. Large ones (≥1,000 matches) run as a background job: the response carries update_id — poll get_list_add_status(list_uid=…, update_id=…) until it completes.
report_data_feedback
ChatGPTReport a data-quality issue on a Grata company — the same 'Report Data Feedback' workflow available on a company profile in the app. Use this when the user spots wrong or missing company data (bad revenue, stale headcount, wrong HQ, a dead company, etc.) and wants to flag it for Grata's data team. Side-effectful — this files a report against the record; confirm with the user before calling. Trigger on "report this data as wrong", "flag the revenue on X", "this company is dead". Required parameters (all three): - company_uid — the company to flag, as a Grata UID (a domain like 'stripe.com' also works if that's what you have). Resolve a company name to a UID first with lookup_companies or ai_search_companies. - issue_category — one of the following exact tokens (a value outside this set is rejected with the valid list, so fix it, do not guess): - dead_company: the company no longer exists / has shut down - executive_contact: an executive or contact detail is wrong - ownership_funding: ownership, investor, or funding data is wrong - revenue: the revenue figure is wrong - employee_count: the headcount is wrong - hq_locations: the headquarters / location is wrong - classification_bm: the industry classification or business model is wrong - description: the company description is wrong - missing_registry: a legal/registry filing is missing (routed to the registry-research queue) - comment: any other data feedback that doesn't fit a category above - details — a short free-text note describing the problem (what's wrong and, when known, the correct value). Required for every category. Returns { status: 'submitted', issue_category, company_uid, details } on success.
request_legal_entity_document
ChatGPTOrder an official document download for a legal entity. This places a document order and uses Grata tokens. Required workflow: (1) call list_legal_entity_documents; (2) show the user the exact document and token_cost; (3) get explicit approval; (4) call with user_approval=True and the same report_id, report_type, report_name, and report_period from the list step. Returns request_id, status, and ready. When ready=true, call fetch_legal_entity_document. Use list_legal_entity_document_requests to check the status of a Processing request. Documents from Austria, the Netherlands, and Norway can take a while to be ready; the user will be emailed when the document is ready for download.
search_active_mandates
ChatGPTReturns individual sell-side M&A mandates currently being marketed for sale. Use this tool when the user asks to find, show, or list specific businesses, assets, or deal opportunities currently on the market. Returns each deal's name, deal_status, transaction_type, location, industries, financials (revenue, ebitda, ebitda_margin, multiples, valuation_expectation), the advisor firm, contact names/emails/phones, and a teaser_link. Note the result's id for a follow-up get_active_mandate. Routing guard: Do not infer this intent from generic references to deals, acquisitions, or M&A activity. Questions about the quantity, volume, or significance of deals are ambiguous unless the user explicitly requests individual businesses or mandates currently marketed for sale. Ask whether the user wants sector-wide PMI metrics, individual businesses currently marketed for sale, or completed transactions, including only the choices plausible for that query. Do not call this tool until the desired output is clear. Clear active mandate requests include: Find software businesses currently for sale, List individual healthcare mandates being marketed in Texas, and Show active sell-side opportunities under $10M EBITDA. Filters: deal_status ('Pre-Market', 'Active', 'Under LOI', 'Closed', 'Expired' — defaults to Active + Pre-Market only if unset), transaction_type ('Acquisition', 'Funding'), industries (free-text → NAICS), location (resolved; special tokens 'USA', 'International', '(US Region)' pass through), revenue/ebitda as [min, max], ebitda_margin as a decimal fraction ≤1.0 (0.20 = 20%, negatives allowed), is_new, is_verified. Pagination: page_size is fixed at 25; page is capped at 100. This is the sell-side mandate tool; for historical closed deals use search_transactions, for a company's own past purchases use get_company_acquisitions.
search_advisory_services
ChatGPTFind accounting firms and legal advisory services — e.g. "tax advisory firms in Texas", "legal services for healthcare M&A". Returns advisory firms with firmographic details. Filters: keywords, service_types (Accounting, Legal Services; omit for both — maps to Operating Model entity filters / NAICS 541211 Accounting and 541110 Legal Services, not primary_business_model_name; verify with the naics field on each row), locations (free-text → HQ-only filter, matching displayed headquarters_pretty, not branch/LOB offices; for a whole country pass its ISO code — United Kingdom→GB, Mexico→MX — not the spelled-out name; for a whole US state spell it out ("California") or use "City, ST" for cities), plus revenue/employees as 2-element [min, max] ranges (either bound nullable). employees filters on the Grata employee estimate (employees_estimate.count), not the headline employee_count — both appear on result rows when known. Pagination: page_size is fixed at 25; page is capped at 100. Distinguish from search_bankers (investment banks / M&A intermediaries) and get_banker_by_id (dealmaker deal history and contacts for bankers).
search_banker_people
ChatGPTFind individual M&A bankers and dealmakers — e.g. "bankers who advised on healthcare deals in North America", "MDs at Lazard with M&A speciality", "bankers based in London". Returns dealmaker people ranked by matched deal activity (deal geography / sector / size), with firm affiliation, current title, location, phone, and LinkedIn. Filters: person_name (individual's name — every token must appear in the stored full name, any order; extra tokens such as a middle initial are fine), company_name (current firm — every token must appear in the firm name, any order), industries (free-text industry names, OR 2-6 digit 2022 NAICS / 8-digit Grata subindustry codes passed directly), locations (where the person's deals took place — free-text city, state/region, country, or greater region; country ISO codes like GB / MX also resolve), person_locations (where the person is based — free-text city (Austin, TX), state/region (Texas, Bavaria), country (Germany or ISO code DE), continent (Europe), UN sub-region (South-eastern Asia), or named area (DACH, Greater Austin, TX Area)), deal_size as 2-element [min, max] nullable range (USD), transaction_roles (direct pass-through), specialities (e.g. M&A, ECM). keywords is retired and returns an error. Pagination: page_size is fixed at 25; page is capped at 100. Distinguish from search_bankers (firm-level advisory intermediaries) and get_company_contacts (Grata executive contacts, not dealmaker deal history).
search_bankers
ChatGPTFind M&A advisors / intermediaries — investment banks and business brokers — e.g. "bankers who advise on healthcare software deals", "most active advisory firms in software M&A". Returns advisory firms with deal activity and profile_url. Which geography filter: a firm's own office and the markets it advises in are separate — "advisory firms headquartered in the Southeast" is headquarters, "bankers who advise companies in Texas" is deal_locations. When the phrasing is bare ("bankers in Texas") it means where the firm sits, so use headquarters. Filters: company_names (firm name or bare domain for named banker/firm lookup — e.g. Houlihan Lokey, bain.com; no https:// or www.), keywords (description / theme text — not firm names), headquarters (free-text → the advisory firm's own office location — use this for "bankers based in X"), industries (free-text sector terms or NAICS codes → ranks firms by deals they actually advised in that sector), deal_locations (free-text → the target company's HQ on the deals a firm advised, i.e. which markets the advisor covers — use this for "bankers who advise companies in X"). For both geography filters: for a whole country pass its ISO code — United Kingdom→GB, Mexico→MX — not the spelled-out name; for a whole US state spell it out ("California") or use "City, ST" for cities, not a bare state code. Also deal_size as a 2-element [min, max] USD range on an individual deal's value, business_models (canonical labels), end_customers, plus revenue/employees as 2-element [min, max] ranges (either bound nullable). employees filters on the Grata employee estimate (employees_estimate.count), not the headline employee_count — both appear on result rows when known. Pagination: page_size is fixed at 25; page is capped at 100. Deal-filtered requests: industries, deal_locations and deal_size all describe the deals a firm advised rather than the firm itself, so any of them ranks advisors by deals actually worked in that deal set, most-active-first, and they combine freely in one query (e.g. industries=['healthcare'], deal_locations=['Texas'], deal_size=[50000000, 100000000]). Each row carries a sector_activity block with rank and deal_count — that is the ranking signal, and deal_count is the denominator to quote when explaining how strong a rank is. deal_count covers the date window reported by data.sector_ranking.deal_window (all time, or since <date> when sort_by='ltm_advised_deal_count' narrows it), so quote that window alongside the number. total_advised_deal_count rides along as the firm's all-time advisory deal count across every sector, geography and size — use it as the denominator for how concentrated the firm is (18 of 40 = specialist, 18 of 900 = generalist), never as the in-filter total. Firm-wide ltm_advised_deal_count is omitted here because it would collide with the in-filter count above; other profile columns (top_sectors, dates, deal size, …) remain firm-wide context, not the score. industries is OR-only across terms; the firm filters (company_names, keywords, headquarters, revenue, employees, business_models, end_customers) are applied together server-side. No client-side re-sorting or set intersection is needed. data.sector_ranking.truncated: true means the firm filters matched more advisors than could be ranked exactly, so the page is a partial view and the filters should be narrowed before trusting the ordering. Note that deals with an undisclosed value cannot match a deal_size band, so a size-filtered count covers disclosed deals only. Activity questions: 'most active firms in [sector]' is just industries=[sector] — results already come back ranked by deals advised there. Add sort_by='ltm_advised_deal_count' to narrow that ranking to the last 12 months; with a deal filter sort_by='total_advised_deal_count' (or no sort_by) ranks all-time deals inside the filters rather than the firm's global total. Deal-filtered results are alwa…
search_buyers
ChatGPTReturns potential acquirer and investor companies — PE firms, strategics, VCs, and family offices. Use this tool when the user asks who might buy or invest in a company, or asks to find, show, or list potential buyers or investors matching a sector and investment profile. For example: Who might buy a $5M EBITDA HVAC company?, Find PE firms that invest in payments, or Which buyers might acquire companies in this sector and deal-size range?. Returns buyer companies with investment history and search_id/profile_url. Routing guard: Do not infer this intent from generic references to buyer interest, buyer activity, buyers being active, acquirer activity, or M&A activity. Use this tool only when the desired output is a list of prospective buyer or investor organizations. If the output is unclear, ask whether the user wants sector-wide PMI buyer metrics, potential buyer organizations, or completed acquisitions, including only the choices plausible for that query. Do not call this tool until the desired output is clear. Buyer type: pass buyer_types to narrow PE / strategic / FO / VC. Accepted labels: Private Equity/PE/Financial Sponsor, Strategic Buyer/Strategic, Family Office/FO, Venture Capital/VC (maps to backend entity_filters: Financial Sponsor vs Strategic Buyer). Family Office/FO and Venture Capital/VC alone also AND a keyword hint (family office / venture capital) because the investors index has no FO/VC entity type; combining them with Private Equity/PE/Financial Sponsor or Strategic/Strategic Buyer drops that keyword so those other types are not excluded. Omit buyer_types to search both financial sponsors and strategics. Named firm lookup: pass company_names (firm name or bare domain — e.g. Morgan Stanley, blackstone.com; no https:// or www.) to find a specific buyer. That is name/domain identity matching, not description text — do not put firm names in keywords. Two filter classes (this is the key nuance): buyer-narrowing filters act on the buyer itself — company_names, buyer_types, keywords, locations (the buyer firm's own HQ, not where its portfolio companies are), revenue, employees, total_investments, preferred_investment_ebitda, preferred_investment_revenue, years_since_relevant_investment. Portfolio-attribute filters — deal_history_keywords, industries, business_models, end_customers — describe the buyer's portfolio / acquired companies, activate the two-phase investment-evidence search, and rank results by deals matching them. Mandate filters narrow to financial sponsors: total_investments, years_since_relevant_investment, preferred_investment_ebitda, and preferred_investment_revenue restrict results to financial sponsors (PE / VC / family offices); strategic and operating-company acquirers are excluded. Say so rather than presenting the result as every buyer. With a portfolio filter present, total_investments bounds deals matching that filter, not the firm's lifetime deal count. Deal History vs Industries: Prefer industries (resolved to NAICS codes on portfolio companies) for sector / industry deal-history queries such as 'find CPG buyers', 'list SaaS acquirers', or 'show healthcare PE firms'. Use end_customers when the theme is an end-customer / vertical tag. Use deal_history_keywords as a free-text fallback for niche themes that are not industries or end-customers; fully resolvable sector phrases are auto-promoted to NAICS portfolio matching. If any term is unresolved, the full list stays on the keyword path (OR'd) so mixed synonym lists are not ANDed across NAICS and keywords; unresolved terms are surfaced in unresolved_names. Param formats: all ranges are 2-element [min, max] with either bound nullable (e.g. total_investments=[5, null]). years_since_relevant_investment is years since the last qualifying deal — the firm's last acquisition, and membership only, not a ranking or a deal count. Last acquisition within 2 years is [0, 2]; none in ove…
search_conferences
ChatGPTFind industry conferences/events. Trigger on "software conferences in 2026", "fintech events in NYC", "trade shows for healthcare". Returns each event's id, name, host, start_date/end_date, location, conference_type (e.g. "Industry Conference"/"Virtual Conference"), industry classification, company_count (how many associated companies are known), and source_link (the conference's own official/external website, e.g. its real homepage — distinct from the Grata-hosted profile_url; may be blank). To get the attendee/exhibitor company list, take the event `id` and call `get_companies_in_list` — conferences are lists. Filters: event_name, industries (2022 NAICS / 8-digit subindustry / free-text — no concatenation, no 7-digit strings), locations, dates (range), participants (a [min, max] range on the number of attending companies, e.g. [50, 500] — NOT a company list), participant_company_uids (company UIDs — returns conferences where any of those companies is a participant; use this to find the conferences a given company attends), conference_type. Pagination: page_size is fixed at 25; page is capped at 100. For events the user has already followed, use get_saved_conferences.
search_legal_entities
ChatGPTSearch Grata legal entity records by text, country, registration number, status, entity type, legal form, industry classification, employees, ownership, and financial metrics. Use this tool by default for European company search when the company is based in a supported European country, the name includes a European legal-form suffix such as AB or GmbH, or the prompt asks about legal-entity financials such as detailed financial statements, equity ratio, solvency, total assets, balance sheet, or leverage; then use get_legal_entities and get_legal_entity_relations as needed for official firmographic data, detailed financial statements, ownership, and people relationships. For group structure of an entity from this search, call get_legal_entity_group_structure with the legal_company_id from the result. For a Grata company, call get_company_legal_entities and then get_company_legal_entity_group_structure with a returned legal_company_id. For broad entity searches, prefer Active entities with a Limited legal form to keep results focused. Use range filters as [min] or [min, max]; ratios and growth metrics use decimal fractions, for example 0.15 for 15%. Returns legal-entity results with details such as name, registration_number, address, website, industries, status, and the latest reported-year financial statements in the requested currency when available.
search_legal_entity_industries
ChatGPTSearch or browse the legal-entity NACE industry vocabulary. Use query to find matching industry nodes, then pass returned level_code values to search_legal_entities as industry_classification.
search_legal_entity_keywords
ChatGPTSearch the legal-entity keyword vocabulary. Use query to find matching keyword entries, then pass returned label values to search_legal_entities as keywords.
search_list_library
ChatGPTSearch the public marketplace of curated/published lists (e.g. Capterra, G2 buyer guides). Trigger on "find a published list about X", "G2's lists", "buyer's guides for Y". Different from get_my_lists, which is the user's own lists. `publisher` vs `search_text` (the key decision): use the exact publisher filter for "lists by X" / "how many X lists" (scopes counts to that publisher); use fuzzy search_text for topic searches like "healthcare lists" (also matches lists merely mentioning a term, so counts differ). classifications accepts 2–6-digit 2022 NAICS, 8-digit Grata subindustry codes, or free-text industry names (resolved server-side) — never concatenate codes or pass 7-digit strings. types filters list type (e.g. "Buyers Guide"); following = "show only"/"hide" to scope to followed lists. Pagination: page_size is fixed at 25; page is capped at 100.
search_transactions
ChatGPTReturns historical/closed M&A transactions across the market — e.g. "software deals over $50M last year", "acquisitions of HVAC companies", "EV/EBITDA multiples in fintech". Returns each transaction's target, acquirer, deal value, and multiples (EV/EBITDA and EV/Revenue), with aggregate statistics over the matching closed transactions. Requires the Deals feature; a caller without it gets a feature_not_in_package error naming the feature, which is not the same as an empty result. Routing guard: Do not infer this intent from generic references to deals, acquisitions, M&A activity, acquirers, or buyer activity. Use this tool only when the user explicitly requests completed, closed, or past transactions; acquisition history; or historical transaction values or multiples. If the lifecycle or desired output is unclear, ask whether the user wants sector-wide PMI metrics, individual businesses currently marketed for sale, completed transactions, or potential buyers, including only the choices plausible for that query. Do not call this tool until the desired output is clear. Filters: target_industries/buyer_companies/target_companies/target_hq, deal_value/ebitda/revenue/employee_size as [min, max], deal_type, has_deal_value/has_deal_multiple booleans, and deal_date=[start, end] ISO strings — a date range is always applied and defaults to the last year, so widen deal_date explicitly for older deals. For a simple trailing window (e.g. "past 2 years"), pass lookback_years instead of computing deal_date yourself — lookback_years=2 sets the range to [today - 2 years, today]. Pass either deal_date or lookback_years, not both. target_industries takes 2022 NAICS codes, 8-digit Grata subindustry codes, or free-text names; never concatenate codes, pass 7-digit strings, or pass "5132 - Software Publishers" as one string (split code and name). target_companies/buyer_companies accept company names (e.g., "Stripe"), domains (e.g., "stripe.com"), or Grata UIDs — all are resolved to UIDs before search. For ambiguous names use lookup_companies first to disambiguate, then pass the id. target_hq is free-text geography resolved server-side — for whole countries pass ISO code (GB, US, MX); US states as "California" or "Georgia, US"; cities as "Austin, TX". Example: target_hq=["GB"] for UK-only deals. Pre-resolved geography dicts (from a prior disambiguation) are also accepted. Pagination: page_size is fixed at 25; page is capped at 100. Distinguish from search_active_mandates (currently on-market) and get_company_acquisitions (one company's purchase history).
sync_company_to_crm
ChatGPTPushes one company into the user's connected CRM (HubSpot, Salesforce, Dynamics, Affinity, etc.). ⚠️ Side-effectful — writes to an external system of record. Confirm before calling. Required: company_uid — a Grata UID (a company domain like 'stripe.com' also works if that's what you have). Syncs the company only unless sync_contacts is set. Trigger on "add X to our CRM", "push this company to our CRM". Resolve a company name to its handle first (lookup_companies). To confirm/retrieve the resulting record afterward, use get_crm_link. For a whole list at once, use sync_list_to_crm.
sync_list_to_crm
ChatGPTPushes every company in a list into the connected CRM (HubSpot, Salesforce, Dynamics, Affinity, etc.). ⚠️ Side-effectful and potentially large — this can create many CRM records at once, so confirm with the user (and ideally confirm the list's size via get_my_lists/get_companies_in_list) before calling. Required: list_uid. Syncs companies only unless sync_contacts is set. Trigger on "sync my … list to CRM", "push that whole list to the CRM". Resolve the list name to its UID first. For a single company, use sync_company_to_crm.
