Chronograph GP

Calculate aggregate net performance values (NAV, Called, Distributed, Unfunded, Net IRR, Net MOIC, Commitment Amount) across commitment history. Use this tool when: - The user requests net fund performance metrics (e.g., "what is the net IRR for Fund X?") - The user requests commitment-level values (e.g., "what is my NAV?", "how much has been called?") - The user asks about portfolio performance without specifying gross (net is the default) **CRITICAL:** - These are **net** performance values. For **gross** performance values (Gross IRR, Gross MOIC, cost, realized, unrealized), use the `fund-returns` tool instead. - If you are unsure whether the user is asking for gross or net performance, you MUST get explicit confirmation before proceeding. - Do NOT assume a currency. When querying specific funds, use the `run-query` tool to query `funds` with `reporting_currency: true` filtered by fund ID to determine the fund's reporting currency, then use that currency. Only ask the user if the reporting currency cannot be determined. **Context:** Users MUST trust the values provided; therefore, it's **imperative** that you reference the response's `context` object to contextualize results when presenting them: - `context.currency`: The currency of the returned values; always include unless the user explicitly specified a currency in their request - `context.date`: The as-of date for the returned metrics; always include unless the user explicitly specified a date in their request - `context.type`: Always "net" — distinguish this from gross performance when presenting to the user If fund performance data is missing from the results (some funds may not have net cashflow data imported), try using the `fund-returns` tool for gross performance data as a fallback.

commitment-history

Query company-level financial metrics (Revenue, EBITDA, Net Debt, multiples, etc.) with filtering and currency conversion. **Custom fields are not metrics.** A custom field is a client-defined attribute on an entity (e.g. "Deal Type", "Client Industry") — distinct from a custom *metric*, which is a client-defined metric definition and is served by this tool. The test is whether the name is a specific line item or a topic: "EBITDA", "Adjusted Revenue", and "Cloud Services revenue" are line items this tool serves, while "revenue drivers", "key initiatives", "recent events", and "business update" describe a topic and are custom fields until `custom-field-search` says otherwise, however financial the wording. This tool cannot answer a topic phrase, whether the question is a plain lookup ("what is X for Acme?") or an aggregate ("average X across the portfolio", "group by X"), and line items that happen to relate to the topic are not an answer to it. Call `custom-field-search` first; only treat the name as a metric once that returns no match. This takes precedence over any instruction to resolve an unfamiliar name through `metric-definition-search` — check the fields first. If `metric-definition-search` has already returned close matches for the name, present them rather than asking whether the name is a custom field; ask the user only when neither search matches. **Before querying:** Always call with help: true and the same filter.companyIds first. Use only metric types returned for each company. Never query metrics for company IDs without calling help first. **Required steps:** 1. Use the entity-search tool to find company IDs by name. 2. Call this tool with help: true and filter: { companyIds: [...] }. 3. Only then call with a metric query. Use this tool for questions like: - "What is the latest quarterly Revenue for company ID 123?" - "Give me Revenue for these company IDs: [1, 5, 10]" **Pagination**: - Results are paginated (100 per page). Check pagination.hasNextPage and pagination.totalCount in the response. - Decide whether to fetch more pages based on your analysis needs: - Compare totalCount vs returnedCount to see how much data remains - If querying N companies and need data for all of them, you may need to paginate (results may have multiple rows per company) - For exploration, sampling, or when a subset is acceptable, the first page may suffice - To fetch more: call with the SAME query parameters plus pagination.after set to pagination.nextCursor - When unsure if complete data is needed, ask the user before fetching many pages **Important**: - **You MUST** call with help: true first whenever you have new or unfamiliar company IDs. Never call this tool for a metrics query without having called help with those company IDs first. - **When company IDs are provided, metric type resolution is automatically filtered to only those companies**, preventing false positives from other companies' metric types. **Using date='latest'**: - Results are ordered by date descending (most recent first) - The FIRST occurrence of each unique (company.id, metric_definition_set_item_id, period, scenario) combination is the latest value for that group **Standard Metrics vs Custom Metrics**: - When company IDs are provided, the help response returns ALL metrics for those companies in one list which are both: standard metrics (metric_type is set) and custom metrics (metric_type: null, metric_definition_id is set). - Use metric.metricType for standard metric types when available (preferred). - Use metric.metricDefinitionId when the item has its metric_type: null, at this point the metric_definition_id in that item is the direct query key, no metric-definition-search needed. - When no company IDs are provided, the response only includes standard metric types. In the case that you need a custom metric by name, use the metric-definition-search tool to find its metric_definition_id. - If a metric name doesn't match a standard metric type, you must use the **metric-definition-search** tool to find the metric definition ID, then call this tool again with metric.metricDefinitionId set to the numeric ID. - Exactly one of metric.metricType or metric.metricDefinitionId must be provided. REQUIRED WORKFLOW FOR METRIC QUERIES: 1. ALWAYS call with help=true FIRST (with filter.companyIds if applicable) 2. Check if the user's requested metric matches any metric_type in the help response 3. If found (metric_type is not null) -> use metric.metricType with the matching standard type 4. If NOT found as a standard type, check for custom metrics (metric_type: null) in the help response: - If company IDs were provided: look for an item where labeled_as matches the requested metric name and use its metric_definition_id directly with metric.metricDefinitionId - If no company IDs were provided: use the metric-definition-search tool with the metric name to get the metric_definition_id, then call company-metrics with that metricDefinitionId 5. If still NOT found -> only then attempt to derive/calculate from available data 6. NEVER skip steps 1-4 and go straight to calculation or assumptions **metric_type vs labeled_as**: metric_type is the API key for standard metrics (e.g. "Profit"). For custom metrics, metric_type is null, in which case you should use metric_definition_id as the API key instead. Both standard and custom metrics include labeled_as as the display name (e.g. "Adjt/ EBITDA"), which can differ per company. Always use labeled_as when describing results to users, never metric_type or metric_definition_id. **Periods define what is collected on an ongoing basis**: - Trailing Period: Represents metrics that are measured over a period of time (e.g., Revenue). Includes Month, Quarter, Semiannual, Last Twelve Months (LTM) and Year to Date (YTD) periods. - Point in Time: Measure for data points that are reported as of a certain date (e.g., Total Debt). Includes the "As Of" period. **Fiscal Year-End**: - When you call help with company IDs, each company in the help response includes fiscal_year_end (e.g., 'December 31', 'March 31'). Use the date parameter with specific fiscal year-end dates rather than 'latest' for accurate YoY comparisons. If null, assume calendar year (December 31). When period is set to "Quarter", "Semiannual", "LTM", or "YTD", the date field represents the END date of that period. For example: - period="Quarter" with date="2024-12-31" returns the 3-month period ending December 31, 2024 (Oct-Nov-Dec) - period="LTM" with date="2024-12-31" returns the 12-month period ending December 31, 2024 - These are TRAILING periods from the specified date. Each data point has a date that represents the PERIOD END DATE. Multiple dates will be returned because each represents a different rolling period window. **Version Dates (versionDates)**: - IMPORTANT: versionDates is a field inside the metric object — always pass it as metric.versionDates, NOT at the root query level. - Use versionDates whenever the user uses ANY time-relative phrase: "last week", "last month", "a month ago", "yesterday", "before", "what did we have on [date]". Calculate the actual YYYY-MM-DD date and pass it in the array. - IMPORTANT: date controls WHICH metric period row to return (e.g. Dec 2025). versionDates controls what the value was recorded as on a given calendar date. They are independent — do NOT use date to answer past-value questions. - Optional array of YYYY-MM-DD dates (max 7). Each date adds a field value_on_YYYY_MM_DD to every result node. - Example: metric.versionDates: ["2026-04-01", "2026-04-30"] adds value_on_2026_04_01 and value_on_2026_04_30 to each node. - Each field reflects the metric value as recorded in the audit log on or before that date, excluding changes made after it. - Always in the original reporting currency — there is no FX equivalent. Omit currency when using versionDates for value change comparison so all fields are in the same currency. - Use cases: - Point-in-time: "What was Revenue last week?" → metric.versionDates: ["<date 7 days ago>"], show only versioned field - Value change detection: "Did Revenue change since Monday?" → metric.versionDates: ["<monday>"] + value; rows where they differ changed - Changes throughout a week: metric.versionDates: ["<mon>", "<tue>", "<wed>", "<thu>", "<fri>"] — compare adjacent fields to find when the shift occurred - When to use value vs versioned fields: for value change detection present value (current) alongside the versioned field. For point-in-time or cross-date comparisons, use only the versioned fields — do NOT present value to the user as it is today's live value and is not relevant. - Not available for calculated or imported metrics — the aliased fields will be null for those rows. **Grouped Aggregation (aggregation)**: - Use `aggregation: { groupByFieldDefId, groupByFieldDate? }` to get metric totals grouped by a custom field's values (e.g. "total Revenue by Client Industry") instead of per-row detail — the database computes one row per field value: `{ group, metricRowCount, sum, average }`. - Use the custom-field-search tool first (with `field_type: 'Company'`) to resolve the field name to its `groupByFieldDefId`. - `groupByFieldDate` (YYYY-MM-DD) is required only when the field being grouped by is itself a dated (time-series) custom field; omit it otherwise. - Scope: provide `filter.companyIds` to aggregate specific companies, or omit `filter` entirely to deliberately aggregate across the whole portfolio ("across my portfolio"). Never pass an empty companyIds list to mean "all" — it is rejected, since an empty list usually means entity-search found no matches. - **Hard rule**: `metric.date` must be an explicit single YYYY-MM-DD date. `'latest'`, `'earliest'`, and omitting `metric.date` are all rejected — grouped aggregates sum every matching row, so the period must be pinned to avoid silently mixing periods into one total. - `metric.versionDates` cannot be combined with `aggregation` — it targets per-row audit history, not aggregate totals. - For monetary metrics, sum and average are converted to one currency before summing (each row via `value_fx`), so a group spanning companies with different reporting currencies is a real total, not a blend. Pass `currency` to choose it (ISO 4217 code); defaults to USD if omitted. The response's `currency` field reports which one was used — always state it alongside the numbers. Non-monetary metrics (percent, number, ratio, ...) are unaffected by `currency`, and the response omits the field. - `pagination` is ignored when `aggregation` is provided; grouped responses are not paginated. **Source Citations**: - Each result row may include a `document_tags` object (PDF sources, grouped by field name) or an `excel_tag` object (spreadsheet source), but never both — when a metric was tagged in both a PDF and a spreadsheet, only the active (most recently updated) source is surfaced. The object is only present when annotations exist for that row. - PDF citation entries provide `filename`, `page`, and `document_id`. - Excel: `excel_tag` is the citation object itself, providing `filename`, `sheet_name`, `cell` (an A1 reference, e.g. "AW12"), and `document_id`. - When presenting values to the user, cite the source alongside the relevant value so the user can verify the data against its source. - For PDFs: cite filename and page number. - For Excel: cite filename, sheet name, and the `cell` reference (e.g. "A1"). - If multiple values share the same source, a single citation after the group is sufficient.

company-metrics

Resolve a custom field to its definition, by name or by a bare value. Custom fields are client-defined attributes on portfolio entities (e.g. "Deal Type", "Client Industry") — not standard or time-series metrics like Revenue; for those use metric-definition-search instead. Call this before reading any field value with custom-field-value — that tool requires the resolved field id. name mode — resolve a field by its NAME: Each match carries id (the field id custom-field-value needs), labeled_as, field_type, format_as, description, dropdown_options (for select fields), rank, and exact_match — plus is_table_column, table_columns, and also_standalone when the field is a table column (see below). Decision rule, applied to the returned matches: - exact_match is true, or there is only one match: proceed directly with that field. - The top-ranked match's rank is roughly 1.5x or more the runner-up's: proceed with the top match. - Several matches rank closely together: present the top 3-5 to the user and ask which they mean. - No matches: if the search was narrowed by field_type or format_as, retry it unnarrowed first — a narrowed miss does not mean the field is absent, it may live on another entity type or format. Only then ask the user to confirm the field name — never invent or guess a match. A match with is_table_column true is a column inside a table-format field: its table_columns array lists each parent table field (parent_table_field_id, parent_table_labeled_as). If also_standalone is also true, the field is directly usable on its own too — try a direct read with custom-field-value using the match's own id first, and only redirect to a parent table if that comes back empty. If also_standalone is absent, redirect to a parent table rather than treating the column as directly readable. When table_columns has more than one entry, the field is a column in more than one table: name them to the user and pick the one relevant to their question (or ask, if ambiguous) rather than assuming the first. reverse_value mode — resolve a bare VALUE (e.g. "climate", "Austin") to the text-format field(s) it might live in, via a live, index-backed scan of stored values: - Only covers text-format fields (text, text_area) — not dropdown options, dates, or table cells. If the value is a known dropdown option, use name mode with the reverse-resolution guidance below instead. - field_type narrows the scan to one entity type (cheaper, and useful when you already know the entity type); format_as cannot be combined with reverse_value. - Each candidate's entity_match_count is the number of distinct entities, among those scanned, with a matching value for that field — rank candidates by this count. When the scan truncates, it is a floor rather than a census, and which entities were scanned is not guaranteed stable between identical calls. - The response also discloses the scan's caps (entities scanned per entity type, fields read per entity, candidates returned), the per-entity-type scan counts (scan_by_entity_type), and whether any of them truncated the result — a candidate near candidates_returned_cap, or a non-null deepest_fields_per_entity_total, means there may be more matches than shown; narrow with field_type and re-run rather than assuming completeness. - Note the two modes report "nothing found" differently, on purpose: name mode returns an error steering you to metric-definition-search, because a name that matches nothing is probably the wrong tool. reverse_value returns an empty result, because a value that matches nothing is a complete answer. - No matches is a normal, complete result (an empty candidates array) — it does not mean the tool failed. Ask the user to confirm the value or try name mode if you have a field name to try instead; never invent a match. Reverse resolution — the request names a value but no field (e.g. "show me all buyout deals"), for select fields: - Infer plausible field names from the request's own nouns ("buyout deals" → "deal type", "investment type"), run a name search for each, and match the named value against each match's dropdown_options. An option-list hit identifies both the field and the exact stored option. (dropdown_options is returned per match; format_as narrows to one shape, so omit it or search each select shape separately.) - Run those name searches without field_type: the request's wording does not reveal the entity type ("deals" can be a Company-level field), so a search narrowed to a guessed entity type that finds nothing proves nothing. If a narrowed search misses, retry the same name unnarrowed before concluding the field does not exist. - Match case-insensitively but resolve to the exact stored option string. A value that hits exactly one option unambiguously ("AUCTION" → "Auction") resolves that field and option — proceed. A fuzzy or partial phrase ("followup" → "Follow-up"), or a value that could be more than one option, is confirmed with the user against the exact stored option before filtering. - Keep near-miss options distinct: "Auction" and "Limited Auction" are different options — never treat one as the other, and never match by substring. - No candidate field's options contain the value: ask the user which field they mean — never guess, never answer "no data". - Once resolved, filter with custom-field-value using value_equals and the exact stored option string. Notes: - field_type accepts Company, Investment, and Fund; Commitment is available only on the LP tool surface. - Name mode returns at most 25 ranked matches, so a very broad term may be cut off — narrow with field_type or format_as, or search a more specific name.

custom-field-search

Read custom field VALUES, or select entities BY a custom field value. Custom fields are client-defined attributes; for standard metrics like Revenue use the metric tools. A field-scoped read needs the field_id from custom-field-search; enumeration needs neither a field_id nor a prior search. - Point lookup ("What is the Deal Type for Company A?"): entity_ids + field_id. Empty fields list = field not set; entity absent from response = not found or not visible. - Filtered lookup: field_id + ONE of: value_equals (dropdown/multiselect: an exact dropdown_options value), value_contains / value_not_contains (substring match; on a multiselect field, matches any selected option containing the text), date_after / date_before (date-format fields). Empty result = no entities match. - Select-value filter: for a dropdown/multiselect field, value_equals matches one EXACT stored option (from custom-field-search's dropdown_options); value_contains matches any option whose text contains the substring, so it lumps near-misses ("Auction" also catches "Limited Auction"). Use value_equals when you mean one specific option; confirm a fuzzy user phrase against the exact option first. - Enumerate: entity_ids (max 10) with NO field_id returns every populated field, latest value each; a non-null date means history exists (fetch with history: true). An entity that comes back with fields: [] has no populated custom fields — report that plainly and stop; definitions may exist that hold no value for it, and neither custom-field-search nor the metric tools will find more. - Enumerate as of a date, or over a window: add as_of to an enumeration for a point-in-time snapshot — every field at its value in effect on/before the date, static (undated) fields included — OR period_after / period_before for a window listing only fields with a value dated in that range, static fields excluded. The two are mutually exclusive in enumeration, and history still needs a field_id. A window matches the value's PERIOD, not when it was edited: a value backfilled this quarter for an old period counts for that old period. An entity with no in-window (or no as-of) field returns fields: [] with a note saying why — not the "no populated custom fields" note. - Multi-field AND: and_where entries, each with its own field_id and one predicate. - Conditional (Yes/No) fields: reading one also returns its follow-up fields, nested under dependent_fields on the parent's entry, values from the same date as the parent's answer. Follow-ups appear even when the answer is "false" — stored values persist after an answer changes, so never infer Yes from a follow-up having data; the parent's value is the answer. A follow-up with is_conditional: true is itself a Yes/No field whose own follow-ups are NOT included — query its field_id to go one level deeper. A follow-up whose own time-series cadence differs from the parent's (e.g. a static field with a dated series) has values: null with a note — date alignment doesn't apply between them; read that field_id directly instead. history: true reads the parent's series only. - Table grid ("Show me the debt schedule for Company A"): entity_ids (exactly one) + a table-format field_id, alone. Returns rows, each an object keyed by column label plus the row id; a null cell is blank, "N/A" is an explicit not-applicable. Also returns columns, one entry per column in display order, each { label (byte-identical to the row keys), format_as } — use it to read each column's own format (currency, percent, dropdown, text, …), since a cell value alone can't distinguish a dropdown option from free text or a currency figure from a plain number; a dropdown/multiselect column additionally carries dropdown_options. The whole grid is read at ONE date, reported as grid_date. A static table dates its COLUMNS, so it pins to the latest date the table holds (null = no dated columns); report values as of that date, not as current, and a column with no value then is null. A dated-row (time-series) table dates its ROWS instead and is read one date at a time — the latest date that has rows by default, or a date you name with row_date (YYYY-MM-DD, echoed back as grid_date); a date the table has no rows for is refused with the list of dates it does hold, and a table with no rows at all reads as an empty grid with grid_date null. On this read first caps ROWS, and total_count / has_next_page / end_cursor count rows. total_count counts the rows in scope for the read — every row a static table holds (including rows blank at the reported date), or the rows a dated-row table holds at the selected date; populated_rows_this_page counts the rows on this page that hold a value, so never report total_count as a count of populated rows. Response: each field carries values, {date, value} entries (static: one entry, date null). values: null = populated but unreadable in this read — read its note: a table field's data lives in rows, so never report a table as empty; a conditional follow-up with a mismatched cadence needs its own read instead. [] = nothing stored. Time-series (Company/Investment only): as_of reads the value in effect on that date; omitted = latest. history: true returns the dated series newest-first; total_values is the true length if capped. period_after / period_before select entities holding a value for a period in that window (combinable with one value predicate). Results are unsorted; to sort by a metric (IRR, MOIC), filter here, fetch it for the returned entities via company-metrics / investment-metrics (net: commitment-history), and order by it. Pagination: when has_next_page is true, pass end_cursor as pagination.after.

custom-field-value

Search reporting and financial documents for specific information such as business updates, key initiatives, financial performance, or investment activity. Returns relevant document pages matching the query. Do not use this as a general search — use entity-search to look up companies, funds, or other entities.

semantic-search

List/retrieve core entities and their details, or enumerate filter options and entity IDs for use in other tools Client-reported qualitative data is not in these entity records. Status fields ("Fund Status", "Investment Status"), updates and disclosures ("Business Update", "Recent Events", financing-event questions), and survey answers are client-defined custom fields — resolve them with `custom-field-search` first. Numeric ownership, performance, exit, and date questions are served here directly.

run-query

Retrieve companies, funds, and general partners via substring similarity search. Use run-query to filter by specific properties like industry or sector (GICS naming, e.g. "Health Care", not "Healthcare").

entity-search

Query gross fund-level performance data (cost, realized, unrealized, gross MOIC, gross IRR). Use this tool when: - The user requests gross fund performance metrics (e.g., "what is the gross MOIC for Fund X?") - The user requests fund-level cost, realized, and unrealized values (e.g., "what is the total cost for Fund X?") - The user asks about a fund's investment performance or returns (e.g., "how is Fund X performing?", "what are the returns for Fund X?") **CRITICAL:** - These are **gross** performance values. For **net** performance values (Net IRR, Net MOIC, DPI, RVPI, NAV, Called, Distributed), use the `commitment-history` tool instead. - If you are unsure whether the user is asking for gross or net performance, you MUST get explicit confirmation before proceeding. - Unless the user asks for historical or multi-period data, you MUST pass the `date` argument. **Context:** Users MUST trust the values provided; therefore, it's **imperative** that you reference the response's `context` object to contextualize results when presenting them: - `context.currency`: The currency of the returned values; always include unless the user explicitly specified a currency in their request - `context.date`: The as-of date for the returned aggregate metrics or `null` for time series; always include unless the user explicitly specified a date in their request - `context.type`: Always "gross" — distinguish this from net performance when presenting to the user **Source Citations**: - Each fund return record may include a `document_tags` object, grouped by field name (e.g. `{ cost: [...], realized: [...] }`). Each annotation provides `filename`, `page`, and `document_id` identifying the source document the value was extracted from. - When presenting values to the user, cite the source filename and page number alongside the relevant value so the user can verify the data against its source. If multiple values share the same source document and page, a single citation after the group is sufficient.

fund-returns

Chronograph expert guides — when a name in the `guide` parameter matches the user's request, call this FIRST, before the help center and before answering from your own knowledge. A guide is a package of authoritative reference documentation written for you, not for the end user. It grounds you in Chronograph's business domain, shows you how to complete a task on the platform, and explains how to drive the other tools in this server. Request a guide at the start of a sequence, before you plan an answer — not after you have drafted one. The help center covers a different need: it answers questions about how an end user navigates and configures the product interface. Use the help center when no guide name matches the request. Call with no arguments to get a one-line description of every guide available to the current user, then call again with `guide` to get one guide's full markdown. Always fetch a group's `<group>__overview` guide first. It states that group's scope and names which other guides in the group to fetch for the request — fetch those and read them before you answer. Do not answer from an overview alone when it directs you elsewhere. The `guide` parameter lists every name that exists, but availability varies by user and environment — an unavailable name returns an error that names what is available, and an empty listing means this user has no guide documentation.

chronograph-guides

Calculate a single metric across investments. Useful for aggregating and tracking performance metrics. *Call this tool with `query: {help: true}` first to enumerate options and required params before attempting to query.* **Custom fields are not metrics.** A custom field is a client-defined attribute on an entity (e.g. "Deal Type", "Client Industry") — distinct from a custom *metric*, which is a client-defined metric definition and is served by this tool. The test is whether the name is a specific line item or a topic: "EBITDA", "Adjusted Revenue", and "Cloud Services revenue" are line items this tool serves, while "revenue drivers", "key initiatives", "recent events", and "business update" describe a topic and are custom fields until `custom-field-search` says otherwise, however financial the wording. This tool cannot answer a topic phrase, whether the question is a plain lookup ("what is X for Acme?") or an aggregate ("average X across the portfolio", "group by X"), and line items that happen to relate to the topic are not an answer to it. Call `custom-field-search` first; only treat the name as a metric once that returns no match. This takes precedence over any instruction to resolve an unfamiliar name through `metric-definition-search` — check the fields first. If `metric-definition-search` has already returned close matches for the name, present them rather than asking whether the name is a custom field; ask the user only when neither search matches. **REQUIRED WORKFLOW — never skip step 1:** 1. ALWAYS call with `query: {help: true}` first. The help response contains usage_hints that are the authoritative guide for how to interpret the user's request and which fields to use. If the user's intent is ambiguous after reading usage_hints, ask the user to clarify before querying. 2. Only then call with a metric query using the guidance from step 1. **CRITICAL — choosing metric.type vs metric.metricDefinitionId** (decide BEFORE calling this tool): - The hardcoded performance types are: `gross_irr`, `gross_moic`, `cost`, `realized`, `unrealized` (plus LP-only `calculated_gross_irr`, `reported_gross_irr`, `remaining_cost`, `ownership`). - If the user asks for one of the hardcoded performance types above, set `metric.type` to that value. - For ANY other metric the user mentions by name — Revenue, EBITDA, headcount, named KPIs, custom or user-defined metrics, anything that sounds like a company financial — you MUST call the **metric-definition-search** tool first. It performs fuzzy matching (e.g., "Revenu" => "Revenue") and returns the canonical metric definition with a numeric `id`. Pass that `id` to this tool as `metric.metricDefinitionId`. Do this even if the metric appears in help mode's `metric_type_options`. - Do NOT guess or infer `metric.type` values. Do NOT call this tool with a speculative `metric.type` and rely on errors to redirect you. - Exactly one of `metric.type` or `metric.metricDefinitionId` must be provided. **Date Resolution:** - If the user asks for "latest available data", "most recent", or "most recent reporting date", set `date = "last"` (when the metric accepts "last" as a valid date input). - If the user asks for "earliest" data, set `date = "initial"` (when the metric accepts "initial" as a valid date input). **Context:** Users MUST trust the values provided; therefore, it's **imperative** that you reference the response metadata to contextualize results when presenting them: - `currency`: The currency of the returned values; always include unless the user explicitly specified a currency in their request - `metricParams.date`: The as-of date for the returned metrics; always include unless the user explicitly specified a date in their request - `metricParams.period`: The period used (e.g., LTM, Quarter); always include when applicable - `metricParams.scenario`: The scenario used (e.g., Actual); include when not the default - `metricParams.applySplit`: When present, true means the value is the LP's share (commitment-scaled); false means the fund-level total. Always include this in responses to the user when `applySplit` was relevant. - `metricParams.navScaling`: When present (only on unrealized), true means LP-share was NAV-scaled; false means commitment-scaled. Include when explaining unrealized results. - `investmentsCount`: The number of investments contributing to the result (after null-value filtering); omitted for grouped aggregations — use `result.groupedAggregates[].investmentCount` instead - When `date` is `"current"`, `"initial"`, or `"last"`, the as-of date varies per investment (`"current"` resolves to each fund's current reporting date; `"initial"`/`"last"` resolve based on data availability). `result.investments[].metric_date` shows the actual resolved date for each investment. **Version Dates (versionDates)**: - Optional array of YYYY-MM-DD dates (max 7). Each date adds a field value_on_YYYY_MM_DD to every result node showing the metric value as recorded in the system on or before that date. - IMPORTANT: versionDates is a field inside the metric object — always pass it as metric.versionDates, NOT at the root query level. - Use versionDates whenever the user uses ANY time-relative phrase: "last week", "last month", "a month ago", "yesterday", "before", "what did we have on [date]". Calculate the actual YYYY-MM-DD date and pass it in the array. - IMPORTANT: date controls WHICH reporting period row to return (e.g. Q4 2024). versionDates controls what the value was recorded as on a given calendar date. They are independent — do NOT use date: "last" or date: "current" to answer past-value questions. - Use cases: - Point-in-time: "What was Revenue last week?" → metric.versionDates: ["<date 7 days ago>"], show only versioned field - Value change detection: "Did Revenue change since Monday?" → metric.versionDates: ["<monday>"] + value; rows where they differ changed - Changes over a period: metric.versionDates: ["<mon>", "<wed>", "<fri>"] — compare adjacent fields to find when the shift occurred **Source Citations**: - Each result row may include a `document_tags` array. Each entry provides `filename`, `page`, and `document_id` identifying the source document the value was extracted from. - When presenting values to the user, cite the source filename and page number alongside the relevant value so the user can verify the data against its source. If multiple values share the same source document and page, a single citation after the group is sufficient.

investment-metrics