add_companies_to_list
ChatGPTAdds or removes a hand-picked set of companies from 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). Set action to "add" (default) or "remove". Maximum 500 items per request. Trigger on "add these to my … list", "put company X on list Y", "remove Z from the 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". Inputs: list_uid plus the search — EITHER the same typed filter kwargs as 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) lets the backend cross-check the match; action="remove" removes all matches instead. 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
ChatGPTDefault tool for company search. Submit 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. Required: query — the user's full natural-language brief. 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 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. Keyword fields (most important to get right): keywords_include/keywords_exclude = how a company describes its own core business; mention_keywords_include/exclude = secondary terms about its end-customers/markets. For "(A or B) and (C or D)" logic use keyword_groups=[["A","B"],["C","D"]] (each inner list is OR, groups are AND'd). Never pass keywords_include together with keyword_groups — the call is rejected. Keyword match depth (`keyword_match`): controls how the keywords_include/keywords_exclude/keyword_groups terms are matched — the same depth control as the Grata UI's search-depth setting. Three modes: • core (default) — the UI's AI Core Focus: semantically expanded matching against a company's core-business description (synonyms/abbreviations included). Widest recall; this is what the tool has always done. • exact — the UI's quoted-phrase matching: each term is matched as an exact phrase with no synonym expansion. Use this to reproduce the precise universe a UI search with quoted keywords builds (e.g. quoting "structural engineering"). Narrowest and most precise; returns fewer companies than core. • mentioned — the UI's Mentioned depth: the looser match that also picks up terms a company mentions about its end-customers/markets (equivalent to routing the same terms through mention_keywords_include). Pick exact when the user wants UI parity or a tightly-scoped list; keep the core default for broad prospecting. mention_keywords_* terms are always matched as mentioned regardless of keyword_match. Resolved free-text fields: locations/locations_exclude — for a whole country pass its 2-letter ISO code, not the spelled-out name: "Mexico"→MX (a bare country name can match a same-named town and return nothing), United Kingdom→GB, Czechia→CZ. US states are NOT ISO codes — spell them out ("California") or use "City, ST" ("Austin, TX"); bare "CA" resolves to Canada, not California. Pass regions/areas as-is ("DACH", "Europe"). industries_include ("software publishers"), lists_include, investors_include, ultimate_owners_include are all resolved server-side; an unresolvable value fails loud (error or unresolved_names warning) rather than silently widening the search. Ranges: revenue_min/max (USD), employees_min/max, funding_min/max, year_founded_min/max, plus growth via employees_change_min/max (percent, −50–500) with employees_change_time ("annual" default). By default a range filter drops companies with unknown values — keep this default for precise results. If a search comes back with too few results to be useful, broaden and re-run (relax keywords and/or set the relevant *_include_unknown flag) instead of returning a near-empty list. Also set a *_include_unknown flag when the user explicitly asks to include companies whose value is unknown/unreported. **Ca…
contacts_companies_contacts_create
ChatGPTGet people/contacts at one or more companies (despite the "create" in its name, this is a read). 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, personal_email, link_linkedin, verified_email.state (e.g. "Deliverable"/"Unknown"), seniority, location, and is_executive. `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/personal 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, 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 personal/work emails. Many rows have blank emails; don't present those as contactable.
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: 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. 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 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.
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 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 search_companies does. keyword_match (core default / exact / mentioned) sets the keyword match depth exactly as in search_companies — use exact for quoted-phrase precision. For ownership_types, pass the convenience value private to match every non-public type at once (the UI's single "Private" filter — 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_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 search_companies, plus seller_intent_score, paginated 25/page with a search_after cursor. For extras like naics, linkedin, or contact fields use enrich_companies or get_company. Seller Intent filter: pass seller_intent_levels to mirror the UI's Seller Intent filter (e.g. ["high_intent"] or ["High Intent"]). Also available on search_companies. 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_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_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 plus component sub-scores (ma_score, vdr_score, advisory_score, investment_bank_score, financial_sponsor_score) and top topics per component (top_5_ma_topics, top_5_vdr_topics, top_5_advisory_topics, top_5_investment_bank_topics, top_5_financial_sponsor_topics). Each row is keyed by calculation_date so you can chart trends over time. 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 breakdown and topics. Time window: optional months (2, 4, 6, 12, 18, or 24; default 2 — past two months). 403: requires the org's package to include Seller Intent (Feature.SELLER_INTENT). Trial-limited orgs 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, personal_email, link_linkedin, verified_email.state, seniority, location, company, and is_executive. `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 contacts_companies_contacts_create 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 personal/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". Returns 404 if the company hasn't been synced yet — in that case offer sync_company_to_crm (with confirmation) rather than treating the 404 as an error. 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_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 corporate group structure for a legal entity by legal_company_id. Use this after search_legal_entities when you need to understand the entity's ultimate parent, group entities, and parent/child ownership relationships.
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`, by list_uid + update_id. Statuses: processing (not done — wait a few seconds and re-poll), complete (final companies_added and list company_count returned), failed (the job errored — offer to retry the add), stuck (processing >10 min — suggest retrying or contacting support). When 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.
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_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. 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_pubf_formula
ChatGPTReturns a verified, ready-to-paste =GRATA.PUBF(...) formula string (or a candidates list when the company is ambiguous) for one company × field × date. 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 an error stating the requirement — relay it and ask the user to enable Comps (or upgrade), rather than retrying. Why this tool: it removes all guessing. You pass structured params and get back strings that are known-correct — never construct or string-stitch a GRATA.PUBF formula, ticker, or exchange suffix yourself. 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. 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 (+0Y), EV/EBITDA (+0Y), EV/Rev (+1Y), EV/EBITDA (+1Y) - 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 (+0Y), EBITDA (+0Y), Revenue (+1Y), EBITDA (+1Y) - 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). - (+0Y) fields (e.g. Revenue (+0Y), EV/Rev (+0Y)) = next fiscal-year projection (first forward year from the anchor date); use when the column is labeled like "2026P" or "next FY revenue". - (+1Y) fields (e.g. Revenue (+1Y), EV/Rev (+1Y)) = the fiscal year after (+0Y) (second forward year); use when the column is labeled like "2027P" or you need one year beyond (+0Y). - 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, or exact domain): { formula: '=GRATA.PUBF("COMP:NYSE", "Revenue (LTM)", "2/15/2026")', ticker, field, date, resolved_company: { uid, name, domain, ticker } } { formula: '=GRATA.PUBF("COMP:NYSE", "Revenue (+0Y)", "2/15/2026")', ticker, field, date, resolved_company: { uid, name, domain, ticker } } Confirm the matched company (name + domain + ticker) to the user. Returns — fuzzy input (bare ticker, name, partial name): { candidates: [ { uid, name, domain, ticker, location, description }, ... ] } ordered best-match first, with NO formula (or a COMPANY_NOT_FOUND error if nothing matches — relay that to the user rather than retrying). Use your judgment: - One clearly dominant match (exact/near-exact name, dominant prefix, st…
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. 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 an error stating the requirement — relay it and ask the user to enable Comps (or upgrade), rather than retrying. 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. 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 and forward (+0Y / +1Y) 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. === 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 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 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_pubf_formula tool to obtain each formula: it returns a verified, ready-to-paste GRATA.PUBF string (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 files, call get_pubf_formula for each (+0Y) or (+1Y) column so every GRATA.PUBF string is certified. == PER-ROW METADATA — REQUIRED == For each peer row, attach hyperlinks and a context note so the audit trail is one click / one hover away: - Company column -> hyperlink to the Grata company profile. Use the profile_url field returned for each company (get_public_comps rows, lookup_companies, and enrich_companies all include it) — do not hand-construct the URL or guess a host/domain. Screen tip: "<Company> — Grata company profile". - Ticker column -> hyperlink to the primary filing URL (latest 10-Q or 10-K on SEC EDGAR; the IR quarterly-results page for foreign filers with no SEC permalink, per the 6-K exception). Screen tip: e.g. "Morningstar Q1 2026 10-Q (EDGAR)". - Ticker column note -> why this public company is in the comp set: the private analog Grata matched and any scale/comparability flag worth surfacing. Example note: "Grata matched a private analog in this peer's segment; Salesforce is a much larger, diversified CRM platform — compare on multiples, not absolute size." Excel auto-styles hyperlinked cells blue-underlined — leave the styling as-is. Do NOT hyperlink other cells in the data grid; keep the data presentation clean. == CITATIONS — MANDATORY == Every GRATA.PUBF cell MUST be written with a source note in the SAME set_cell_range call that writes the formula — never a follow-up pass (follow-ups get skipped under context pressure). Use the cell note field (classic Excel note, hover-to-view), NOT threaded comments. Citations split into three buckets by source type: (A) Market-data fields — NO filing citation (continuously-updated quotes; tying them to one quarterly filing is misleading). Use the note that matches the metric variant: - Share Price: 'Source: Market data (unadjusted closing price as of <anchor date>); not a quarterly-filing line …
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 the billing period dates. 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.
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 named company to its Grata handle. Use this the moment the user names a specific company ("get me Apple", "pull Stripe's financials") and you need the company handle to call any get_company*, enrich_companies, get_public_comps, or contacts tool. Returns up to 100 exact name/domain/ticker matches (each with id, name, description, domains, employees_estimate, headquarters_pretty, profile_url, priority, firm_roles), or empty if none. Results are score-ordered: priority 0 is the best match. Single required param: query — a name ("Stripe"), domain ("stripe.com"), or ticker. Expect homonyms: a query like "Stripe" returns the fintech plus unrelated firms sharing the name, so disambiguate by firm_roles/domains/description/headquarters_pretty and pass the matching company's id (a domain is also accepted) downstream. Not a discovery tool. For "all companies named X" or any full paginated set, use search_companies(name_contains=…). For "companies like X", use find_similar_companies. 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.
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 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).
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 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.
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_bankers
ChatGPTFind M&A advisors / intermediaries — investment banks and business brokers — e.g. "bankers who advise on healthcare software deals", "intermediaries in the Southeast", "most active advisory firms in software M&A". Returns advisory firms with deal activity and profile_url. 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), industries (free-text sector terms → keyword text search on firm descriptions; not NAICS / firm self-classification), locations (free-text → HQ filter; 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), 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. Industries AND-vs-OR semantics: industries is OR-only — each term is searched as a keyword against intermediary firm text (approximates deal-sector coverage; verify via enriched top_sectors on results). There is no AND mode. To find firms covering BOTH sectors at once: 1. search_bankers(industries=['healthcare']) → collect company_uids 2. search_bankers(industries=['software']) → collect company_uids 3. Intersect the two sets client-side 4. Optionally confirm both sectors appear in enriched top_sectors on the intersecting rows Activity questions: for 'most active firms in [sector]', filter with industries/keywords and pass sort_by='ltm_deal_count' (deals closed in the last 12 months) or sort_by='total_deal_count' (all-time) to rank the results server-side — no client-side re-sorting. sort_direction defaults to 'desc' (most active first); pass 'asc' for least active. Requires Dealmaker Profiles access; without it the request is rejected. Enriched rows still expose ltm_deal_count, deal size range, sector breakdown (top_sectors), recent deals, and deal team. Data freshness: each firm profile exposes is_stale (true when most_recent_deal_date > 12 months ago). No per-contact verification timestamp or confidence score is available. Distinguish from search_buyers (the principals who acquire) and from search_active_mandates (the actual mandates being shopped).
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. Two filter classes (this is the key nuance): buyer-narrowing filters act on the buyer itself — keywords, revenue, employees, total_investments, preferred_investment_ebitda, preferred_investment_revenue, years_since_relevant_investment. Portfolio-attribute filters — deal_history_keywords, industries, locations, business_models, end_customers — describe the buyer's portfolio / acquired companies and activate the two-phase investment-evidence search. 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]). industries/locations are free-text resolved server-side (for locations, pass a country's 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); business_models must be canonical labels (no "SaaS"/"B2B"). Pagination: page_size is fixed at 25; page is capped at 100. Sorting by deal activity: pass sort_by='ltm_deal_count' (deals closed in the last 12 months) or sort_by='total_deal_count' (all-time) to rank the most active buyers directly — no client-side re-sorting. sort_direction defaults to 'desc' (most active first); pass 'asc' for least active. Omit sort_by to keep default relevance ordering. Requires Dealmaker Profiles access; without it the request is rejected. Typical check size: use preferred_investment_ebitda and preferred_investment_revenue to scope by deal size. Enriched rows may include stated target_equity_cheque_down/up and sector breakdown when Dealmaker Profiles entitlement applies. Portfolio companies: search_buyers returns buyer firms with investment evidence; it does not enumerate portfolio companies. To see a buyer's portfolio, call get_company_acquisitions with the buyer's company_uid (returns deals where that company was the acquirer), or use search_transactions with buyer_companies=[company_uid]. Deal team contacts: enriched rows may include active_deal_team (names and seniority) when Dealmaker Profiles entitlement applies. Email/phone/LinkedIn per contact is not available in the dealmaker profiles data model. Data freshness: enriched rows may expose is_stale when most_recent_deal_date > 12 months. No last_verified_at timestamp or `…
search_companies
ChatGPTTool for "find me companies that…" requests. Translate a natural-language prospecting query into structured filters 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. Reach for this whenever the user describes a type of company rather than naming one. 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. Keyword fields (most important to get right): keywords_include/keywords_exclude = how a company describes its own core business; mention_keywords_include/exclude = secondary terms about its end-customers/markets. For "(A or B) and (C or D)" logic use keyword_groups=[["A","B"],["C","D"]] (each inner list is OR, groups are AND'd). Never pass keywords_include together with keyword_groups — the call is rejected. Keyword match depth (`keyword_match`): controls how the keywords_include/keywords_exclude/keyword_groups terms are matched — the same depth control as the Grata UI's search-depth setting. Three modes: • core (default) — the UI's AI Core Focus: semantically expanded matching against a company's core-business description (synonyms/abbreviations included). Widest recall; this is what the tool has always done. • exact — the UI's quoted-phrase matching: each term is matched as an exact phrase with no synonym expansion. Use this to reproduce the precise universe a UI search with quoted keywords builds (e.g. quoting "structural engineering"). Narrowest and most precise; returns fewer companies than core. • mentioned — the UI's Mentioned depth: the looser match that also picks up terms a company mentions about its end-customers/markets (equivalent to routing the same terms through mention_keywords_include). Pick exact when the user wants UI parity or a tightly-scoped list; keep the core default for broad prospecting. mention_keywords_* terms are always matched as mentioned regardless of keyword_match. *Prefer keywords for what a company does. Put industry, sector, and business-model phrases (e.g. "pallet industry", "pet food", "HVAC services", "managed IT") in `keywords_include` — it matches how companies describe themselves and gives the most precise results. Use specific, multi-word keywords that name the niche (e.g. "legal practice management software", "wealth management software"), not single broad terms ("legal", "wealth") that match far too many companies. Use `industries_include` only for an explicit NAICS/SIC code or an explicit request to filter by formal industry classification; it resolves to broad NAICS buckets that over-return for a plain industry phrase. Resolved free-text fields: `locations`/`locations_exclude` — for a whole country pass its 2-letter ISO code, not the spelled-out name: "Mexico"→`MX` (a bare country name can match a same-named town and return nothing), United Kingdom→`GB`, Czechia→`CZ`. US states are NOT ISO codes — spell them out ("California") or use "City, ST" ("Austin, TX"); bare "CA" resolves to Canada, not California. Pass regions/areas as-is ("DACH", "Europe"). `industries_include` ("software publishers"), `lists_include`, `investors_include`, `ultimate_owners_include` are all resolved server-side; an unresolvable value fails loud (error or `unresolved_names` warning) rather than silently widening the search. Ranges: `revenue_min/max` (USD), `employees_min/max`, `funding_min/max`, `year_founded_min/max`, plus growth via `employees_change_min/max` (percent, −50–500) with `employees_change_time` ("annual" default). By default a range filter drops* companies with unknown values — keep this default for pre…
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, get_legal_entity_relations, and get_legal_entity_group_structure as needed for official firmographic data, detailed financial statements, ownership, people relationships, and group structure. 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. Access depends on the Grata package: if it returns "No approval received", tell the user access to this tool depends on their Grata package rather than reporting "no results". 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. 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). 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. 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.
