Grata

Returns a ready-to-paste =GRATA.PERIOD_END(...) formula string (or a candidates list when the company is ambiguous) for one company × field × date. The evaluated cell is the fiscal period-end date of the most recently reported period for that field as of the date argument — not a financial value. Use this ONLY when the deliverable is an Excel file — either the user is working in the Grata Excel add-in, OR has asked from any surface (including chat) for an .xlsx of public comps — and you need a period-end DATE column. For metric VALUE columns use get_public_financials_formula; for filing-date columns use get_filing_date_formula. For inline content (markdown tables, analysis, Q&A in conversation) use get_public_comps instead, which returns VALUES — never paste raw =GRATA.PERIOD_END(...) strings into chat text, where they cannot evaluate, and do not invent period-end dates inline (get_public_comps has no period_end JSON fields). Requires the Comps feature (matches the Grata web app and Excel add-in). It is included by default in the Scale and Alpha packages, and lower-tier packages can have it enabled too (add-on, per-org grant, or trial) — so do NOT assume a package tier. Callers without the Comps feature receive a `feature_not_in_package` error naming the required feature; retrying won't change the result. Why this tool: you pass structured params and get back a formula whose field name and date the server has checked and whose ticker it resolved — never construct or string-stitch a GRATA.PERIOD_END formula, ticker, or exchange suffix yourself. It does not check that Grata has data for that combination. Parameters: - company: a flexible identifier — Grata UID, ticker (with or without :EXCHANGE), domain, or company name. Natural-language names resolve via the same search that backs the add-in's 'Find Company'. - field: the exact field name (case-insensitive) — one of the strings below. A near-miss returns an error listing valid entries, so fix it, do not guess. The field selects which metric's reporting period to date (same catalog as GRATA.PUBF). Share Price returns the unadjusted EOD closing price; Share Price Adj returns EOD adjusted_close (split-and-dividend-adjusted). Field catalog: - Valuation: Share Price (unadjusted closing price), Share Price Adj (split-and-dividend-adjusted close), Outstanding Shares, Market Cap, Enterprise Value, EV/Rev (LTM), EV/EBITDA (LTM), EV/EBIT (LTM), EV/Gross Profit (LTM), Price/Earnings Ratio, EV/Rev (FY1), EV/EBITDA (FY1), EV/Rev (FY2), EV/EBITDA (FY2) - Income Statement: Revenue (LTM), EBITDA (LTM), EBITDA Margin (LTM), Gross Profit (LTM), Gross Margin (LTM), EBIT (LTM), EBIT Margin (LTM), Quarterly Revenue, Qtr Rev Growth (YoY), Qtr Earnings Growth (YoY), Tax Rate (LTM), Revenue (FY1), EBITDA (FY1), Revenue (FY2), EBITDA (FY2) - Balance Sheet: Net Debt, Debt/Equity Ratio - Cash Flow: Operating Cash Flow Margin (LTM), Free Cash Flow Margin (LTM) Forward period semantics — pick the suffix to match the column header, not the calendar year alone: - (LTM) fields (e.g. Revenue (LTM), EV/EBITDA (LTM)) = trailing twelve months ending on the date argument; use for the most recently reported period (e.g. CY2025A as of a March 2026 anchor). - (FY1) fields (e.g. Revenue (FY1), EV/Rev (FY1)) = first annual fiscal year-end in Earnings.Trend after the period end of the most recent filing available as of the date argument (not the raw calendar date). Companies with different fiscal calendars (e.g. WMT Jan 31 vs AMZN Dec 31) get different FY1 period ends for the same input date. An input date between a period close and its filing date uses the prior filing, not the unfiled period. Use when the column is labeled like "2026P" or "next FY revenue". - (FY2) fields (e.g. Revenue (FY2), EV/Rev (FY2)) = the second annual fiscal year-end after that same last-filed period end (the year after FY1); use when the column is labeled like "2027P" or you need one year beyond (FY1). Legacy names such as Revenue (+0Y) and Revenue (+1Y) are accepted and normalized to Revenue (FY1) and Revenue (FY2). - date: an "MM/DD/YYYY" string anchoring the as-of window (e.g. "2/15/2026") — the same window GRATA.PUBF uses. Must fall between 1/1/2020 and today (data is unavailable before 2020 and for future dates); an out-of-range date returns an error. Returns — unambiguous input (UID, full TICKER:EXCHANGE, or exact domain): { formula: '=GRATA.PERIOD_END("COMP:NYSE", "Revenue (LTM)", "2/15/2026")', ticker, field, date, resolved_company: { uid, name, domain, ticker } } { formula: '=GRATA.PERIOD_END("COMP:NYSE", "Revenue (FY1)", "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, strong contextual fit) → re-call with that candidate's UID or full TICKER:EXCHANGE and proceed without bothering the user (e.g. "Compass" → COMP:NYSE; "Compass Group" → CMPGY:PINK). - Genuine ambiguity between plausible candidates → present them (name + domain + ticker + location) and re-call after the user picks. Laying out a comps table: call this once per (company × metric × period) for period-end DATE columns. Put the returned ticker into the ticker column, the field into the metric header row, and the date into a single anchor cell, then write the body as cell references — =GRATA.PERIOD_END($B2, C$1, $B$1) — so the model stays live and copy-fillable. The tool produces the three strings; you lay them out. Value columns still go through get_public_financials_formula; filing-date columns through get_filing_date_formula. After delivering the file, tell the user they must be logged into the Grata Excel add-in for the cells to evaluate.

get_period_end_formula

**Returns 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_mcp_tool_costs

**Full 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_active_mandate

**Single banker (M&A advisor / intermediary) firm profile by Grata `company_uid`.** Resolve a UID with `search_bankers` or `lookup_companies` first. **Returned fields:** - Firmographic: `name`, `domain`, `firm_type`, `firm_role`, `description`, `city`, `country`, `greater_regions`, `linkedin`, `primary_phone`, `primary_email`, `year_founded`, `employees`, `estimated_revenue_usd` - **Coverage:** When `firm_profiles` enrichment is missing, the payload includes `coverage_note`. Relay that note. Missing `ltm_deals` / `nl_summary` are not zero activity and must not be invented. Search-card `ltm_advised_deal_count` / `total_advised_deal_count` may still be present — report them if present. Principal / acquisition counts (`total_deal_count` / `ltm_deal_count`) are not on this profile. When `coverage_note` is absent, deal-activity fields come from `firm_profiles`. - **Deal counts — three distinct windows, never substitute one for another:** `total_advised_deal_count` (all-time advisory), `ltm_advised_deal_count` (trailing 12 months — use for "how active is this advisor?"), `ytd_deal_count` (calendar year-to-date, counted from announcement dates in `ltm_deals` — not a separately role-scoped counter). YTD is always ≤ LTM, and is legitimately much smaller than LTM early in a calendar year. Report the window the user asked for and label it explicitly. A null `ytd_deal_count` means it could not be derived — say so rather than reporting LTM as YTD. Principal / acquisition counts (`total_deal_count` / `ltm_deal_count`) are not on this profile — use `get_buyer_by_id` / `search_buyers` when the user wants buy-side activity for the same firm. - **Deal size range:** `avg_deal_value` and `median_deal_value` (USD); `deal_value_p25` / `deal_value_p75` are the role-scoped disclosed-value percentiles and `primary_side` is buy or sell. Per-deal values are in `ltm_deals[]` (same rows as `advised_deals[]`). - **Sector breakdown:** `top_sectors` — array of `{grata_title, count, dealmakers[]}`, sorted by deal count descending. Use `count` for sector concentration. - **Buy-side vs sell-side split:** `total_buy_side_advised_parties` and `total_sell_side_advised_parties` — the sides of the deals this firm **advised on**: buy side = it advised the acquirer, sell side = it advised the seller. Use their ratio for "is this advisor more buy-side or sell-side?". Deals where the firm acted on its own account (e.g. its own bolt-on acquisition) are excluded; for those use `get_buyer_by_id`. - **Timeline:** `first_deal_date`, `most_recent_deal_date` - **Recent deals (LTM):** `ltm_deals` — each entry has `{deal_title, announcement_date, deal_value, transaction_type, sectors[], principals[{name, principal_type}], dealmakers[{full_name, ml_user_id, current_seniority, transaction_role}], dealmaker_attribution}`. `principals` are deal-party *companies* (buyer/seller/banker firms), not people. **Per-deal people:** when `dealmaker_attribution` is `available`, `dealmakers` lists the named individuals attributed to that transaction. When it is `unavailable`, `dealmakers` is empty — do **not** invent names from `active_deal_team` or `top_sectors[].dealmakers`. Use `get_banker_person` only when the user wants that person's full deal history. Never count these entries to state how many deals a firm has done in any window — use `total_advised_deal_count` / `ltm_advised_deal_count` / `ytd_deal_count`. - **Deal team / top advisors:** `active_deal_team` — array of `{full_name, current_seniority}`, the firm's current dealmakers (use this for "top advisors at <firm>" and to check whether a named person is currently at the firm). Names and seniority only; no email, phone, or LinkedIn per individual contact. When `coverage_note` is absent, an empty or omitted list means no bankers are linked yet — say so rather than rendering an empty table. For deal-team contact details, search `search_active_mandates` for active mandates with advisor filter. - **Freshness:** `is_stale` (bool) — `true` when `most_recent_deal_date` is older than 12 months. No `last_verified_at` timestamp or `data_confidence` score is available in the data model; `is_stale` is the only freshness signal. - **AI narrative:** `nl_summary` (auto-generated firm summary; activity line uses advised LTM for bankers) **Access:** requires Dealmaker Profiles entitlement. Returns 403 if not entitled.

get_banker_by_id

**Dealmaker-network profile for one banker/professional by `person_id`.** `person_id` is the MergerLinks `ml_user_id` from `search_banker_people`. Use after `search_banker_people` when the user wants deal history, principals, or sector detail. **Returned fields:** identity (`first_name`, `last_name`, seniority/speciality), current firm (`company_name`, `company_uid`, `firm_role`), deal totals (`lifetime_deal_count`, value range, first/last deal dates), `top_sectors` / `top_regions`, and a **recent sample** of `deals` (capped for context size — use `lifetime_deal_count` for how many deals the person has overall, not `len(deals)`).

get_banker_person

**Single buyer (PE firm / strategic / VC / family office) profile by Grata `company_uid`.** Resolve a UID with `search_buyers` or `lookup_companies` first. **Returned fields:** - Firmographic: `name`, `domain`, `firm_type`, `firm_role`, `description`, `city`, `country`, `greater_regions`, `linkedin`, `primary_phone`, `primary_email`, `year_founded`, `employees`, `estimated_revenue_usd` - **Coverage:** When `firm_profiles` enrichment is missing, the payload includes `coverage_note`. Relay that note. Missing `ltm_deals` / `nl_summary` are not zero activity and must not be invented. Search-card `ltm_deal_count` / `total_deal_count` may still be present — report them if present. When `coverage_note` is absent, deal-activity fields come from `firm_profiles`. - **Preferred check size (deal size range):** `target_equity_cheque_down` and `target_equity_cheque_up` (integers in `fund_currency`, defaulting to USD when `fund_currency` is null — the firm's stated investment range). May be null if the firm has not disclosed criteria. - **Deal counts — three distinct windows, never substitute one for another:** `total_deal_count` (all-time principal / acquisition), `ltm_deal_count` (trailing 12 months — use for "how active is this buyer?"), `ytd_deal_count` (calendar year-to-date, counted from announcement dates in `ltm_deals` — not a separately role-scoped counter). YTD is always ≤ LTM, and is legitimately much smaller than LTM early in a calendar year. Report the window the user asked for and label it explicitly. A null `ytd_deal_count` means it could not be derived — say so rather than reporting LTM as YTD. Advisory / banker counts are not on this profile — use `get_banker_by_id` / `search_bankers` when the user wants advised-deal activity for the same firm. - **Deal size statistics:** `avg_deal_value` and `median_deal_value` (USD, based on historical closed deals). `deal_value_p25` / `deal_value_p75` are the role-scoped percentiles and `primary_side` is buy or sell. Acquisition history is `acquisition_deals[]` (same rows as `ltm_deals[]`). - **Sector breakdown:** `top_sectors` — array of `{grata_title, count, dealmakers[]}`, sorted by deal count descending. Use `count` for sector concentration. Sector `dealmakers` are people active in that sector (top 5 sectors only), not a per-deal lead list. - **Portfolio / investment activity:** `buy_side_principal_count` and `sell_side_principal_count`; `ltm_deals` — each entry has `{deal_title, announcement_date, deal_value, transaction_type, sectors[], principals[{name, principal_type}], dealmakers[{full_name, ml_user_id, current_seniority, transaction_role}], dealmaker_attribution}`. `principals` are deal-party *companies*, not people. **Per-deal people:** when `dealmaker_attribution` is `available`, `dealmakers` lists the named individuals attributed to that transaction. When it is `unavailable`, `dealmakers` is empty — do **not** invent names from `active_deal_team` or `top_sectors[].dealmakers`. Never count `ltm_deals` entries to state deal activity — use `total_deal_count` / `ltm_deal_count` / `ytd_deal_count`. For the firm's **full portfolio / complete acquisition history**, use `search_transactions(buyer_companies=[company_uid])` (or `get_company_acquisitions` for a strategic's own purchases). - **Timeline:** `first_deal_date`, `most_recent_deal_date` - **Deal team contacts:** `active_deal_team` — array of `{full_name, current_seniority}`. Names and seniority only; no email, phone, or LinkedIn per individual contact. When `coverage_note` is absent, an empty or omitted list means no deal team members are linked yet — say so rather than rendering an empty table. - **Freshness:** `is_stale` (bool) — `true` when `most_recent_deal_date` is older than 12 months. No `last_verified_at` timestamp or `data_confidence` score is available; `is_stale` is the only freshness signal. - **AI narrative:** `nl_summary` (auto-generated firm summary) **Access:** requires Dealmaker Profiles entitlement. Returns 403 if not entitled.

get_buyer_by_id

**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 company shape as `ai_search_companies`, paginated 25/page with a `search_after` cursor. For extras like naics, linkedin, or contact fields use `enrich_companies` or `get_company`. When summary-first rows are active, rows after the top 5 are id/name/domain stubs (plus `profile_url`) — expand them with `enrich_companies` (batch, up to 10 per call); this tool has no `fields` argument, so there is no uniform-full-row re-run. **Seller Intent filter:** pass `seller_intent_levels` (e.g. `["high_intent"]` or `["High Intent"]`). Also available on `ai_search_companies`. **CRM membership filter:** pass `in_crm="only"` to keep just the companies on this list that are already matched to a record in the org's CRM, or `"exclude"` for the ones that are not — use it for "which of these are already in our CRM" rather than calling `get_crm_link` per company. To rank conferences by CRM overlap, call this once per conference UID with `in_crm="only"` and compare the returned `count`. **Conferences are lists too:** for a conference's "attendees / exhibitors / speakers / sponsors / the list", pass the *conference's* UID here. Resolve names to a `list_id` first — `get_my_lists` or `search_list_library` for regular lists, `search_conferences` or `get_saved_conferences` for events. Requires the UID — it does not accept a list name.

get_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 `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

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

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

Get the registered legal entities of a Grata company by company_uid. Use this when the user starts from a company (name, domain or UID) and asks for its registry financials, shareholders, officers or group structure: pass the returned legal_company_id values to get_legal_entities or get_legal_entity_relations. For the corporate group, if get_company_legal_entity_group_structure is in your tool list, call it with a returned legal_company_id. If it is not listed, call get_legal_entity_group_structure with that legal_company_id. Each entity carries its country, registration number and flags: is_canonical (the company's main entity), is_canonical_in_country (the main entity in its country) and is_servable (its financial statements may be shown). An empty list means the company has no registry match.

get_company_legal_entities

Get the corporate group for one registry entity. legal_company_id comes from get_company_legal_entities. Returns the ultimate parent, companies, parent/child relations, and is_oversized, member_count and relation_count from the group structure row. An oversized group has empty companies and relations and still returns the counts. There is no company match check. Always reads the exported dataset.

get_company_legal_entity_group_structure

**Seller Intent detail for one `company_uid`.** Returns month-over-month seller intent history: composite `seller_intent_score` per `calculation_date`, so you can chart trends over time. Component sub-scores and topics (M&A, VDR, Advisory, Financial Sponsor, Investment Bank) are not exposed through this tool. **Requires a UID** — resolve a name with `lookup_companies` first. **Pair with `get_company`:** `get_company` returns only the latest headline `seller_intent_score`; this tool returns the full historical trend. **Time window:** optional `months` (2, 4, 6, 12, 18, or 24; default 2 — past two months). **403 / visibility:** requires the org's package to include Seller Intent (`Feature.SELLER_INTENT`, Alpha). Orgs without that package do not see this tool and cannot call it. Trial-limited orgs that do have access may receive zeroed scores for the most recent 12 months.

get_company_seller_intent

**Get people/contacts at one or more companies.** Trigger on "who's the CEO/CFO of X", "decision-makers at X", "contact info for X's execs", "get me emails at these companies". Required: `company_uids` — each a Grata UID (a company domain like 'stripe.com' also works when you don't have the UID) — a non-empty list; resolve names via lookup_companies. Returns per contact: name, `current_title`/`normalized_current_title`, `work_email`, `link_linkedin`, `verified_email.state` (e.g. "Deliverable"/"Unknown"), seniority, location, and `is_executive`. Each company carries `profile_url`, the Grata company profile where the full contact details are shown. **`contact_type`:** `"execs"` (executives only), `"user"` (contacts you've added), `"all"` (both; the default if omitted). `list_id` scopes to contacts within a saved list. **Filters:** `has_email` / `has_linkedin` (booleans — keep only contacts with a work email, or a LinkedIn URL). `email_status` (list; any of `deliverable`, `risky`, `unknown`, `undeliverable`, `pending`) keeps only contacts whose work-email verification is in those states. `departments` (list) accepts only `"exec"` (executives) or numeric position IDs — it is NOT a free-text department search, so pass `["exec"]` to narrow to executives. `query` is a free-text match over contact name, company name, work email, and title. **Sorting:** `sort_field` one of `company`, `department`, `recency`, `has_email`; `sort_direction` `asc` or `desc` (both must be supplied together to take effect). **Handle the data responsibly:** results include real work emails. Many rows have blank emails; don't present those as contactable.

get_company_contacts

**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`, `link_linkedin`, `verified_email.state`, seniority, location, `company`, and `is_executive`. `_web_url` opens the list's contacts page in Grata, where the full contact details are shown. **`contact_type`:** `"execs"` (executives only), `"user"` (contacts you've added/unlocked), `"all"` (both; default). **Pagination:** `page` (default 1), `page_size` (default 25, max 100). Large lists can have thousands of contacts — paginate rather than requesting everything at once. **When to use which tool:** prefer this for list-scoped contact workflows (one call, server-side pagination). Use `get_company_contacts` when you already have specific `company_uids` and need per-company grouping or filter/sort params (`has_email`, `query`, `departments`, etc.). **Handle the data responsibly:** results include real work emails. Many rows have blank emails; don't present those as contactable.

get_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 legal registry group structure for a legal entity by legal_company_id from search_legal_entities. Returns the ultimate parent, the companies in the group, and parent/child ownership. Draw ownership_stake, or max_ownership_stake when ownership_stake is absent. Empty companies and relations means there is no structure to draw. A company_count and no companies or relations means the group exists but is too large to draw. This is not the Grata-enhanced group graph; that graph will be get_grata_enhanced_group_structure.

get_legal_entity_group_structure

Get the minority ownership above a legal entity. legal_company_id comes from search_legal_entities or get_company_legal_entities. Returns owners (companies and people, no minimum stake), owner-to-owned relations, and ultimate owners. This is not the subsidiary group graph; use get_legal_entity_group_structure for that graph. Draw ownership_stake, or max_ownership_stake when ownership_stake is absent. Empty owners and relations means there is no structure to draw. is_oversized, or a note with no owners or relations, means the graph exists but is too large to draw; the counts are complete. truncated_direct_owner_count is direct owners omitted upstream, not an incomplete total.

get_legal_entity_minority_ownership

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` or `remove_search_results_from_list`**, by `list_uid` + `update_id`. Statuses: `processing` (not done — wait a few seconds and re-poll), `complete`, `failed` (the job errored — offer to retry with the tool the response names), `stuck` (processing >10 min — suggest the same retry or contacting support). When an add is `complete`, compare `companies_added` with the `matched_count` from the submit response: a lower number usually means some matches were already in the list or the add reached the plan's list-size limit — tell the user the actual added count rather than reporting a plain success. When a remove is `complete`, report the new `list_company_count`.

get_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. - Target size (target_size): the sector's employee-headcount mix among companies behind its current deal-room activity, as a bucket→percentage map. Buckets: 1-50=SMB, 51-250=Middle Market, 251-5000=Upper Middle Market, 5000+=Enterprise, Unknown=headcount not available. Percentages sum to ~100. Omitted when no headcount data is available for the sector. Metrics include start/end, annual_volatility, and available momentum windows. Specific-sector results also include min/max extrema; broad scans and market comparisons do not. Compare deal activity score, buyer activity score, and buyer commitment score because they can diverge. For industries requests, uncovered codes appear in insufficient_data_naics_codes (too little coverage) or unknown_naics_codes (no PMI data found). Mixed requests return covered results plus these lists; a request fails only when no code is covered.

get_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. Inline VALUES use the same engine as GRATA.PUBF: the same (ticker, field, date) is the same number, stored at warehouse four-decimal ratio scale (e.g. 11.8476 — present those digits; do not round multiples to one decimal in chat tables). For chat comps tables, as-of history, and multi-year trends, call this tool (one `as_of` per call) and answer with a markdown table of VALUES. Do not call get_public_financials_formula, get_period_end_formula, or get_filing_date_formula, and do not offer to create an Excel file, unless the user asked for an .xlsx. Requires the Comps feature (matches the Grata web app and Excel add-in). It is included by default in the Scale and Alpha packages, and lower-tier packages can have it enabled too (add-on, per-org grant, or trial) — so do NOT assume a package tier. Callers without the Comps feature receive a `feature_not_in_package` error naming the required feature; retrying won't change the result. Pass the company's `company_uid` — a Grata UID (a company domain like 'stripe.com' also works if that's what you have); use lookup_companies first if you only have a name. Optional `as_of` is an LTM-anchor date as MM/DD/YYYY. Omit it (or pass today) for current snapshot values. A historical date re-evaluates every row through the same engine as GRATA.PUBF for that date, then recomputes stats. Dates before 1/1/2020 or after today return DATE_OUT_OF_RANGE — tell the user there is no data; do not invent numbers. This tool accepts at most one `as_of` per call — there is no `dates[]`. A multi-year trend in chat is N calls (one date each), answered as a markdown table of VALUES; do not create an Excel file unless the user asked for one, and do not paste GRATA.PUBF strings in chat. To target calendar year YYYY, pass 2/15 of YYYY+1 (after that year's close, before the next quarter reports): CY2020 → 2/15/2021 … CY2024 → 2/15/2025. Each returned company includes a `pubf_ticker` field already formatted as TICKER:EXCHANGE (e.g. "MSFT:NASDAQ") — use it verbatim; never guess a ticker symbol or exchange suffix. Inline VALUES include LTM metrics, market-data fields (`share_price`, `share_price_adj`, `outstanding_shares` — the same engine as GRATA.PUBF Share Price / Share Price Adj / Outstanding Shares, including today), and forward (FY1 / FY2) fields in the JSON (e.g. revenue_0y, revenue_1y, ebitda_0y, ebitda_1y, ev_over_rev_0y, ev_over_rev_1y, ev_over_ebitda_0yr, ev_over_ebitda_1yr). Use the returned keys for inline tables — do not guess or invent alternate field names. In GRATA.PUBF / GRATA.PERIOD_END, (FY1) / (FY2) anchor to the last filing available as of the date argument (period end of that filing, then the next two annual Trend dates) — not the raw calendar date. This JSON has no period_end or filing_date value fields — do not invent those dates inline. === For Excel-file deliverables (opt-in) === If the deliverable is an Excel file — whether the user is working directly in the Excel add-in OR has asked from any surface (including chat) for an .xlsx to be created — construct GRATA.PUBF / GRATA.PERIOD_END / GRATA.FILING_DATE formulas from the conventions below so the file is live and refreshable when opened. If the deliverable is inline (markdown table, analysis, Q&A in conversation), return values directly — do NOT output raw GRATA.PUBF, GRATA.PERIOD_END, or GRATA.FILING_DATE strings in chat text, where they cannot evaluate. The trigger is "an Excel file is being produced," not "the user is in the add-in." Prefer the dedicated get_public_financials_formula tool to obtain each formula: it returns a ready-to-paste GRATA.PUBF string with a checked field and date (and resolves company names to the right TICKER:EXCHANGE) so you never string-stitch a ticker, field, or date yourself. For inline chat tables, use the JSON forward keys above (revenue_0y, revenue_1y, etc.); for Excel files, call get_public_financials_formula for each (FY1) or (FY2) column so every GRATA.PUBF string is checked. Period-end DATE columns: call get_period_end_formula (fiscal period-end date of that field as of the anchor — not a financial value). Filing-date DATE columns: call get_filing_date_formula. == 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 (FY1 / FY2) 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 (FY1 / FY2) 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 (FY1 / FY2) -> 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 (FY1), EV/EBITDA (FY1), EV/Rev (FY2), EV/EBITDA (FY2) - Income Statement: Revenue (LTM), EBITDA (LTM), EBITDA Margin (LTM), Gross Profit (LTM), Gross Margin (LTM), EBIT (LTM), EBIT Margin (LTM), Quarterly Revenue, Qtr Rev Growth (YoY), Qtr Earnings Growth (YoY), Tax Rate (LTM), Revenue (FY1), EBITDA (FY1), Revenue (FY2), EBITDA (FY2) - Balance Sheet: Net Debt, Debt/Equity Ratio - Cash Flow: Operating Cash Flow Margin (LTM), Free Cash Flow Margin (LTM) - 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. - Period-end / filing-date columns use the same three arguments and the same cell refs. Canonical date cells: =GRATA.PERIOD_END($B2, C$1, $B$1) and =GRATA.FILING_DATE($B2, C$1, $B$1). The field argument is the adjacent metric (e.g. C$1 = "Revenue (LTM)"), not a header like "Period End". Get them from get_period_end_formula / get_filing_date_formula; never stitch. - 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. PERIOD_END / FILING_DATE cells are dates, not filing line items — do not apply buckets A/B/C. A short note is enough (period-end or filing date of the adjacent metric as of the anchor). Never hardcode those dates as values. - 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. Do not emit a second (prior-year) date cell unless a trailing derived column actually references it — an unused dated header cell reads as an input and analysts may edit it expecting a refresh. - Worked example (CY2025A / CY2026P / CY2027P as of March 2026): ONE anchor cell $B$1 = 2/15/2026 (no prior-year date cell); 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 (FY1)" — get it from get_public_financials_formula. 2027P revenue cell: =GRATA.PUBF($B2, E$1, $B$1) where E$1 = "Revenue (FY2)". Forward periods use those native FY1 / FY2 fields on the same LTM-anchor cell — never a second date. Optional LTM date columns: =GRATA.PERIOD_END($B2, C$1, $B$1) and =GRATA.FILING_DATE($B2, C$1, $B$1). - Trailing YoY quarterly growth: prefer native catalog fields on the single LTM-anchor cell — "Qtr Rev Growth (YoY)" and "Qtr Earnings Growth (YoY)" — do not rebuild them with a second date. - Trailing derived metrics with NO native field (LTM revenue growth, YoY margin change, multi-year CAGRs): only then add a second prior-period anchor cell and reference it (never a hardcoded date). If the sheet has no such column, omit the prior-year cell entirely. Example: $C$1 = 2/15/2025 referenced from the derived column: =GRATA.PUBF($B2, "Revenue (LTM)", $B$1) / GRATA.PUBF($B2, "Revenue (LTM)", $C$1) - 1 A field missing from the catalog is NOT a missing capability; do not fall back to hardcoded values. - Statistics block: match the UI Public Comps view. After the company rows (one blank separator), always add Mean then Median for EVERY numeric metric — including size and absolute-value columns (Market Cap, EV, Revenue, EBITDA, EBIT, Gross Profit, Quarterly Revenue, Net Debt, Revenue FY1/FY2, EBITDA FY1/FY2) plus all ratios, margins, and Beta. Mean is primary and listed before Median; both are always present. Optionally extend with Max / 75th percentile / 25th percentile / Min below Median. Compute on full-precision GRATA.PUBF values (do not wrap cells in ROUND); apply number formats for display only. Ignore unavailable / blank / error cells so they do not distort Mean (Excel AVERAGE / MEDIAN skip blanks; use AGGREGATE to skip errors). For EV/EBITDA and P/E columns, also 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: =AVERAGE(IF(K$7:K$12>0, K$7:K$12)); =MEDIAN(IF(K$7:K$12>0, K$7:K$12)); and for the extended set =MAX(IF(K$7:K$12>0, K$7:K$12)); =QUARTILE(IF(K$7:K$12>0, K$7:K$12), 3); =QUARTILE(IF(K$7:K$12>0, K$7:K$12), 1); =MIN(IF(K$7:K$12>0, K$7:K$12)). Do not exclude size columns from stats. - 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

Returns a ready-to-paste Excel formula, =GRATA.PUBF(...), that looks up one public-company financial figure (a valuation, income-statement, balance-sheet or cash-flow metric) in Grata's public financials for one company × field × date, or a candidates list when the company is ambiguous. Use this ONLY when the deliverable is an Excel file — either the user is working in the Grata Excel add-in, OR has asked from any surface (including chat) for an .xlsx of public comps. For inline content (markdown tables, analysis, Q&A in conversation) use get_public_comps instead, which returns VALUES (including revenue_0y, revenue_1y, and related forward keys) — never paste raw =GRATA.PUBF(...) strings into chat text, where they cannot evaluate. Requires the Comps feature (matches the Grata web app and Excel add-in). It is included by default in the Scale and Alpha packages, and lower-tier packages can have it enabled too (add-on, per-org grant, or trial) — so do NOT assume a package tier. Callers without the Comps feature receive a `feature_not_in_package` error naming the required feature; retrying won't change the result. Why this tool: you pass structured params and get back a formula whose field name and date the server has checked and whose ticker it resolved — never construct or string-stitch a GRATA.PUBF formula, ticker, or exchange suffix yourself. It does not check that Grata has data for that combination. Parameters: - company: a flexible identifier — Grata UID, ticker (with or without :EXCHANGE or .EXCHANGE), domain, or company name. Natural-language names resolve via the same search that backs the add-in's 'Find Company'. - field: the exact field name (case-insensitive) — one of the strings below. A near-miss returns an error listing valid entries, so fix it, do not guess. Share Price returns the unadjusted EOD closing price; Share Price Adj returns EOD adjusted_close (split-and-dividend-adjusted). Field catalog: - Valuation: Share Price (unadjusted closing price), Share Price Adj (split-and-dividend-adjusted close), Outstanding Shares, Market Cap, Enterprise Value, EV/Rev (LTM), EV/EBITDA (LTM), EV/EBIT (LTM), EV/Gross Profit (LTM), Price/Earnings Ratio, EV/Rev (FY1), EV/EBITDA (FY1), EV/Rev (FY2), EV/EBITDA (FY2) - Income Statement: Revenue (LTM), EBITDA (LTM), EBITDA Margin (LTM), Gross Profit (LTM), Gross Margin (LTM), EBIT (LTM), EBIT Margin (LTM), Quarterly Revenue, Qtr Rev Growth (YoY), Qtr Earnings Growth (YoY), Tax Rate (LTM), Revenue (FY1), EBITDA (FY1), Revenue (FY2), EBITDA (FY2) - Balance Sheet: Net Debt, Debt/Equity Ratio - Cash Flow: Operating Cash Flow Margin (LTM), Free Cash Flow Margin (LTM) Forward period semantics — pick the suffix to match the column header, not the calendar year alone: - (LTM) fields (e.g. Revenue (LTM), EV/EBITDA (LTM)) = trailing twelve months ending on the date argument; use for the most recently reported period (e.g. CY2025A as of a March 2026 anchor). - (FY1) fields (e.g. Revenue (FY1), EV/Rev (FY1)) = first annual fiscal year-end in Earnings.Trend after the period end of the most recent filing available as of the date argument (not the raw calendar date). Companies with different fiscal calendars (e.g. WMT Jan 31 vs AMZN Dec 31) get different FY1 period ends for the same input date. An input date between a period close and its filing date uses the prior filing, not the unfiled period. Use when the column is labeled like "2026P" or "next FY revenue". - (FY2) fields (e.g. Revenue (FY2), EV/Rev (FY2)) = the second annual fiscal year-end after that same last-filed period end (the year after FY1); use when the column is labeled like "2027P" or you need one year beyond (FY1). Legacy names such as Revenue (+0Y) and Revenue (+1Y) are accepted and normalized to Revenue (FY1) and Revenue (FY2). - date: an "MM/DD/YYYY" string anchoring the GRATA.PUBF LTM window (e.g. "2/15/2026"). Must fall between 1/1/2020 and today (data is unavailable before 2020 and for future dates); an out-of-range date returns an error. Returns — unambiguous input (UID, full TICKER:EXCHANGE / TICKER.EXCHANGE, or 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 (FY1)", "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, strong contextual fit) → re-call with that candidate's UID or full TICKER:EXCHANGE and proceed without bothering the user (e.g. "Compass" → COMP:NYSE; "Compass Group" → CMPGY:PINK). - Genuine ambiguity between plausible candidates → present them (name + domain + ticker + location) and re-call after the user picks. Laying out a comps table: call this once per (company × metric × period). Put the returned ticker into the ticker column, the field into the metric header row, and the date into a single anchor cell, then write the body as cell references — =GRATA.PUBF($B2, C$1, $B$1) — so the model stays live and copy-fillable. The tool produces the three strings; you lay them out. After delivering the file, tell the user they must be logged into the Grata Excel add-in for the cells to evaluate.

get_public_financials_formula

**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 `token_period_end_date` — when the current token period ends. Trigger on "how many tokens do we have left", "are we near our limit". For a *per-teammate breakdown* of how that consumption splits across the team (the MCP portion), use `get_company_mcp_usage` — same pool, different cut.

get_token_usage

List this organization's document download requests for a legal entity, most recent first. Includes in-flight (Processing), completed (Done), and failed requests for any teammate in the organization. Use it to check an existing request's status. When status is Done, call fetch_legal_entity_document with request_id.

list_legal_entity_document_requests

List official source documents available for download for a legal entity (including annual reports, interim reports, and other registry filings). Use after resolving legal_company_id via search_legal_entities or get_legal_entities. Returns document_id, document_name, document_type, document_period, and token_cost. This tool only lists documents; it does not place an order. First step before request_legal_entity_document. Pagination: page defaults to 1 and page_size defaults to 20.

list_legal_entity_documents

**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 specific organization identity from a company name, domain, ticker, or registration number. Returns score-ranked company and legal-entity candidates; `rank` 0 is the best match. Read `entity_type` before using a result: a company has its company UID in `id`, while a legal entity has its internal identifier in `data.legal_company_id` and its `id` is not a company UID. Expect homonyms and disambiguate using the type-specific `data`. This tool resolves a known identity; it does not discover, paginate, or find similar sets of organizations.

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 `ai_search_companies` (`keywords_include`, `revenue_min`, `name_contains`, …; for `locations`/`locations_exclude` pass a country's ISO code (UK→"GB", Mexico→"MX"), not the spelled-out name; spell out a whole US state ("California")); as an escape hatch you may pass a prior search's `filters` dict via `filters`, but never mix flat keys into that dict (the backend rejects it). **Exporting a `find_similar_companies` result set?** Pass the *same* seed you gave that tool — `company_uid` (single) or `company_uids` (list), each a UID (a domain also works if that's what you have) — alongside the same filters. This reproduces the ranked similarity set; omitting the seed silently previews a broader filter-only search (more rows, including off-target matches).

preview_export_cost

**Removes a hand-picked set of companies from an existing list.** ⚠️ *Destructive — deletes entries from a saved list.* Confirm before calling. Provide the `list_uid` (from `get_my_lists`) and `company_uids` when you have them, or `domains` if that's all you have (exactly one of the two; domains are resolved server-side). Maximum 500 items per request. Trigger on "remove Z from the list", "take X off my list". To remove every company matching a search, use `remove_search_results_from_list` instead. Returns the updated list size — report that; the backend does not count how many companies were actually taken off the list. UIDs/domains that did not resolve are echoed in `unresolved_company_uids`/`unresolved_domains`. Resolve a company or list *name* to its UID first.

remove_companies_from_list

**Removes EVERY company matching a search from a list, server-side, in one call.** ⚠️ *Destructive — deletes entries from a saved list.* Confirm before calling. Trigger on "remove everything matching … from my list", "take all the <segment> companies off the list". To remove specific companies by UID or domain, use `remove_companies_from_list` instead. **Inputs:** `list_uid` plus the search — EITHER the same typed filter kwargs as `ai_search_companies`, OR `filters` = the `filters_used` dict returned by a prior search (don't mix flat keys into it), OR `similar_to_company_uids` (up to 10 seed companies — each a UID or a domain — combinable with typed kwargs). Optional `deselected_company_uids` (UIDs; domains also accepted) keeps specific matches on the list ("all except these"); `expected_count` (the total from the prior search, minus any `deselected_company_uids`) lets the backend cross-check the match; a mismatch is rejected. At least one real constraint is required — match-everything requests are refused. Small result sets apply immediately and return the new list size; report that, since the backend does not count how many companies were actually taken off the list. Large ones (≥1,000 matches) run as a background job: the response carries `update_id` — poll `get_list_add_status(list_uid=…, update_id=…)` until it completes.

remove_search_results_from_list

**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 ai_search_companies. - `issue_category` — one of the following exact tokens (a value outside this set is rejected with the valid list, so fix it, do not guess): - dead_company: the company no longer exists / has shut down - executive_contact: an executive or contact detail is wrong - ownership_funding: ownership, investor, or funding data is wrong - revenue: the revenue figure is wrong - employee_count: the headcount is wrong - hq_locations: the headquarters / location is wrong - classification_bm: the industry classification or business model is wrong - description: the company description is wrong - missing_registry: a legal/registry filing is missing (routed to the registry-research queue) - comment: any other data feedback that doesn't fit a category above - `details` — a short free-text note describing the problem (what's wrong and, when known, the correct value). Required for every category. Returns `{ status: 'submitted', issue_category, company_uid, details }` on success.

report_data_feedback

**Order an official document download for a legal entity.** This places a document order and uses Grata tokens. **Required workflow:** (1) call list_legal_entity_documents; (2) show the user the exact document and token_cost; (3) get explicit approval; (4) call with user_approval=True and the same report_id, report_type, report_name, and report_period from the list step. Returns request_id, status, and ready. When ready=true, call fetch_legal_entity_document. Use list_legal_entity_document_requests to check the status of a Processing request. Documents from Austria, the Netherlands, and Norway can take a while to be ready; the user will be emailed when the document is ready for download.

request_legal_entity_document