Grata

**Return 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 rich company shape as `search_companies` (name, domain, revenue, employees, NAICS, ownership, `profile_url`, `seller_intent_score`), paginated 25/page with a `search_after` cursor. **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_companies_in_list

**The 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 `get_banker_by_id`, and for a **PE firm / strategic / VC / family-office buyer**, prefer `get_buyer_by_id` (where available) — those return deal counts, sector concentration, deal-size range, check size, and the active deal team, which this generic profile does not.

get_company

**Per-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_mcp_usage

**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_live_deals`.

get_company_acquisitions

**Exit 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. **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_exit_readiness

**Revenue 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_financials

**Round-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_funding_rounds

**The 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_investors

**Seller 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_company_seller_intent

**Get 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.

contacts_companies_contacts_create

**Return 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_contacts_in_list

**Poll 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_export_status

Get 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_entities

Get 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_group_structure

Get 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_legal_entity_relations

**Poll 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_list_add_status

**List 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_my_lists

Returns 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_private_market_indices

Returns 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. === 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. == 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 item.' - Share Price Adj: 'Source: Market data (split-and-dividend-adjusted closing price as of <anchor date>); not a quarterly-filing line item.' - Outstanding Shares, Market Cap: 'Source: Market data (unadjusted closing price as of <anchor date>); not a quarterly-filing line item.' (B) Filing-derived fields — single Source line: 'Source: <Filing type> <Period>, <Section> <Direct URL to filing>'. Example: 'Source: Form 10-Q (Q1 2026, qtr ended 3/31/2026), Item 1, Condensed Consolidated Statements of Income https://www.sec.gov/Archives/edgar/data/.../morn-20260331.htm'. (C) Hybrid fields (market + filing) — cite only the filing component and name the market one: Enterprise Value -> 'Source: Market cap (unadjusted closing price × shares outstanding, market data) + Net Debt; Net Debt from <Filing> <Period>, Item 1, Condensed Consolidated Balance Sheets <URL>'. Rules (bucket B and the filing portion of C): Section must be specific ("Item 1, Condensed Consolidated Balance Sheets"; "Item 2, MD&A Non-GAAP reconciliation" — not just "10-Q"). The URL must be the actual document on SEC EDGAR (or the equivalent local regulator archive), not the IR landing page (exception: 6-K filings with no SEC permalink — the IR quarterly-results page is OK). Forward (+1Y) metrics cite the earnings call / outlook page, not the 10-Q. Precedence: SEC EDGAR > local regulator > IR page > earnings press release. Per-metric source-type routing: - Share Price -> A (market): unadjusted closing price; no filing - Share Price Adj -> A (market): split-and-dividend-adjusted closing price; no filing - Outstanding Shares, Market Cap -> A (market): market data, no filing - Enterprise Value -> C (hybrid): Net Debt from the Balance Sheet; market cap noted as market data - Net Debt, Debt/Equity -> B: Item 1, Condensed Consolidated Balance Sheets - Revenue, Gross Profit/Margin, EBIT/Margin, EPS, P/E -> B: Item 1, Statements of Operations/Income - EBITDA, EBITDA Margin, EV/EBITDA -> B: Item 2, MD&A Non-GAAP reconciliation - Cash flow margins -> B: Item 1, Statements of Cash Flows - EV/Revenue, EV/EBITDA, P/E multiples (LTM) -> B: same source as the underlying numerator/denominator - Forward (+1Y) metrics -> B: earnings call / outlook / management guidance page REQUIRED PRE-STEP: before writing notes, resolve each peer's latest filing URL on SEC EDGAR (via web_search). Special cases: foreign private issuers file 6-K under IFRS — cite the IR quarterly-results page (no SEC permalink). Off-calendar fiscal years — use the correct fiscal-period label (e.g. Salesforce Jan FYE -> 'FY2026 10-K (yr ended 1/31/2026)'; Intapp June FYE -> 'fiscal Q3 FY2026 10-Q'). Forward (+1Y) -> cite the most recent earnings call / outlook page, NOT the most recent 10-Q. GRATA.PUBF conventions: - Ticker format: TICKER:EXCHANGE (e.g. MSFT:NASDAQ, JPM:NYSE). Use the `pubf_ticker` value this tool returns per company — it already carries the correct primary exchange suffix. - Function syntax: =GRATA.PUBF("TICKER:EXCHANGE", "Field Name", "MM/DD/YYYY") - Field catalog (use these exact strings): - 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 (+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 (+1Y), EBITDA (+1Y) - Balance Sheet: Net Debt, Debt/Equity Ratio - Cash Flow: Operating Cash Flow Margin (LTM), Free Cash Flow Margin (LTM) - Build tables with CELL REFERENCES, never hardcoded string arguments. All three GRATA.PUBF arguments should reference cells so the model stays live and editable: - Ticker -> a column of tickers (e.g. $B2, $B3, ...) - Field name -> a header row of metric titles (e.g. C$1, D$1, ...) - Date -> a single anchor-date cell (e.g. $B$1) Canonical body cell: =GRATA.PUBF($B2, C$1, $B$1) — copy-fillable across the whole table. Hardcoded string arguments (=GRATA.PUBF("MORN:AMEX", "Revenue (LTM)", "2/15/2026")) are acceptable only for one-off cells outside a table; inside a comps table, hardcoding breaks the "all formulas, all live" principle and forces users to edit every cell to swap a ticker, metric, or period. - Dollar-denominated fields (Market Cap, Enterprise Value, Revenue (LTM), EBITDA (LTM), Gross Profit (LTM), Net Debt, Revenue (+1Y), EBITDA (+1Y)) return raw dollars — divide by 1,000,000 in the formula to display $M, by 1,000,000,000 for $B. - Citations are MANDATORY for every GRATA.PUBF cell — see the CITATIONS section above; write the note in the SAME set_cell_range call that writes the formula. - Date argument = LTM window anchor: the date anchors an LTM window ending on it. To target a calendar year, pass a date in the gap between fiscal year-end and the next quarter's earnings — e.g. for CY2025 use 2/15/2026 (after Q4'25 close, before Q1'26 reports). Put it in one anchor cell and reference it across the table. - Worked example (CY2025A / CY2026P as of March 2026): anchor cell $B$1 = 2/15/2026; tickers in column $B (rows 2–6); metric headers in row 1 (columns C onward). 2025A revenue cell: =GRATA.PUBF($B2, C$1, $B$1) where C$1 = "Revenue (LTM)". 2026P revenue cell: =GRATA.PUBF($B2, D$1, $B$1) where D$1 = "Revenue (+1Y)". - Derived metrics: figures not in the catalog (LTM growth, YoY margin change, multi-year CAGRs) are built by calling the same field at two different dates and doing the arithmetic in-cell. Use a second anchor cell for the prior-period date (e.g. $C$1 = 2/15/2025). CY2025 revenue growth: =GRATA.PUBF($B2, "Revenue (LTM)", $B$1) / GRATA.PUBF($B2, "Revenue (LTM)", $C$1) - 1 Treat this as a first-class workflow, not a workaround — a field missing from the catalog is NOT a missing capability; do not fall back to hardcoded values. - Statistics block: for comparable metrics (margins, multiples) add Max / 75th percentile / Median / 25th percentile / Min, with one blank row separating the company data from the stats rows. For EV/EBITDA and P/E columns, filter out non-positive values (negative or zero EBITDA / earnings make these multiples not meaningful) with dynamic-array formulas (no CSE), e.g. over a K7:K12 range: =MAX(IF(K$7:K$12>0, K$7:K$12)); =QUARTILE(IF(K$7:K$12>0, K$7:K$12), 3); =MEDIAN(IF(K$7:K$12>0, K$7:K$12)); =QUARTILE(IF(K$7:K$12>0, K$7:K$12), 1); =MIN(IF(K$7:K$12>0, K$7:K$12)). Size columns (Market Cap, EV, Revenue, EBITDA) are typically excluded from stats since absolute size is not comparable across different-scale peers; include them only if the user asks, labeled "for reference". - Caveats: non-calendar fiscal years (e.g. Microsoft = June, Oracle = May) — clarify expected behavior with the user. If a date falls inside a reporting gap for one company but not another, periods may be silently mixed; document any such gap explicitly rather than guessing. - After delivering the file, tell the user they must be logged into the Grata Excel Add-in for the cells to evaluate (if they are not already evaluating).

get_public_comps

**The 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_saved_conferences

**The 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.

get_token_usage

**Log 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.

logout

**Resolve 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`.

lookup_companies

**Step 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).

preview_export_cost

**Report 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.

report_data_feedback

**Find 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_advisory_services

**Find 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 or `get_banker_by_id`). There is no AND mode. To find firms covering BOTH sectors at once: 1. `search_bankers(industries=['healthcare'])` → collect `company_uid`s 2. `search_bankers(industries=['software'])` → collect `company_uid`s 3. Intersect the two sets client-side 4. Optionally call `get_banker_by_id` per uid to confirm both sectors appear in `top_sectors` **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 — use `get_banker_by_id` per `company_uid` for the full profile. **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_live_deals` (the actual mandates being shopped).

search_bankers

**Returns 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. Full profile (including stated `target_equity_cheque_down`/`up` and sector breakdown) is returned by `get_buyer_by_id` given the result's `company_uid`. **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:** the search result does not include individual contact details. Call `get_buyer_by_id` for `active_deal_team` (names and seniority). Email/phone/LinkedIn per contact is not available in the dealmaker profiles data model. **Data freshness:** `is_stale` on `get_buyer_by_id` profiles indicates when `most_recent_deal_date` > 12 months. No `last_verified_at` timestamp or `data_confidence` score is available. Use this for the *buy-side*; for the firms *advising* on a sale use `search_bankers`.

search_buyers

**Tool 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, employees, ownership, NAICS, funding, `profile_url`). 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 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. **Categories:** see the `ownership_types` parameter description for its allowed values and the `private` convenience rollup (mirrors the UI's single **"Private"** ownership filter). `business_models` (canonical labels only — Software, Software Enabled, Services, Retailer, Manufacturer, Distributor, Producer, Marketplace, Content & Publishing, Hospitals & Medical Centers, Investment Banks & Business Brokers, Private Equity & Venture Capital, Staffing & Recruiting, Colleges & Universities, Government, Nonprofit & Associations, Private Schools, Religious Institutions, US Federal Agencies; "SaaS"/"B2B" are rejected). **Location types:** see the `location_types` parameter description for its allowed values and the equivalent of the UI's **include all non-headquarter locations** toggle. **Exit readiness:** `exit_readiness_signals` surfaces deal-sourcing signals — `founder_age_signal` (founders at transition age), `hold_period_signal` (PE/investor hold period ending; alias of the backend's `transaction_signal`), `funding_signal` (no recent funding). Multiple values are match-any (a company matching any selected signal is returned). **Seller Intent:** pass `seller_intent_levels` (`["high_intent"]` / `["High Intent"]`, etc.) to filter by Intent to Sell buckets. Pass `sort_by='seller_intent'` (optional `sort_direction` `'asc'`/`'desc'`, default `'desc'`) to order by Seller Intent *band* — not by raw score: `'desc'` returns High Intent to Sell first, then Has Intent to Sell, then companies with no detected intent last; `'asc'` reverses that band order. No score ranking within a band. Requires Seller Intent package access. **Disambiguation:** for "every company *named* X" use `name_contains`, not this tool's keywords and not `lookup_companies`. For "companies *like* company X" use `find_similar_companies`. **Fields:** use `fields` to select which company fields to return (fewer fields fit more companies per page). **Pagination:** one page (25) at a time; to advance, re-send identical filters with `page` incremented and `search_after` set to the previous response's cursor (page capped at 100). Pages are sequential — never bulk-fetch.

search_companies

**Find 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_conferences

Search 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_entities

Search 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_industries

Search the legal-entity keyword vocabulary. Use query to find matching keyword entries, then pass returned label values to search_legal_entities as keywords.

search_legal_entity_keywords

**Search 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_list_library

**Returns 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_live_deals` (currently on-market) and `get_company_acquisitions` (one company's purchase history).

search_transactions

**Pushes 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_company_to_crm

**Pushes 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`.

sync_list_to_crm