MSCI Connector

Get PCI-enabled profiles for the authenticated user. Returns: Dictionary with profiles list, profile_count, access_status, and optional environment. On Platform API failure, returns status api_error with error and user_guidance (same shape as get_measure_detail downstream failures).

get_pci_user_profiles

ROUTING — Real Assets direct property & fund data. Trigger: 'property index', 'real estate index', 'IPD', 'direct property', 'capital growth', 'income return', 'standing investments', '[Country] Quarterly/Annual Property Index'. NOT for equity indices, factor indices, or listed portfolios (use AIIndexInsights/TPM). Prefer ``get_rai_metadata`` first; use this tool for full lists, debugging, or when metadata returns poor candidates. Load ``instructions.md`` first via ``get_rai_reference_docs(doc_name="instructions")`` if not already in context. TOKEN COST GUIDE — call only what you need: • ``datasets`` → ~12,000 tokens (fallback when metadata fails for dataset) • ``measures`` → ~4,000 tokens (fallback when metadata fails for measures) • ``segmentations`` → ~23,000 tokens ⚠️ MOST EXPENSIVE. Only when metadata returned zero segmentation candidates AND user asked for a specific segmentation. • ``segmentation_nodes`` → <500 tokens (only after segmentation_id is known) Args: resource: One of: ``datasets``, ``measures``, ``segmentations``, ``segmentation_nodes``. product_ids: For ``measures``: optional comma-separated product IDs. product_id: For ``segmentations`` / ``segmentation_nodes``: optional product ID. as_of_date: Optional as-of date (YYYY-MM-DD). segmentation_id: Required for ``segmentation_nodes``. Simple (e.g. ``"2"``) or cross-segmentation (e.g. ``"264::2"``). measure_ids: Comma-separated IDs → full detail objects; omit → trimmed list. dataset_ids: Comma-separated IDs → full detail objects; omit → trimmed list. search_text: For ``segmentation_nodes`` only: optional name filter.

get_rai_catalog

ROUTING — Real Assets direct property & fund data. Trigger: 'property index', 'real estate index', 'IPD', 'direct property', 'capital growth', 'income return', 'standing investments', '[Country] Quarterly/Annual Property Index'. NOT for equity indices, factor indices, or listed portfolios (use AIIndexInsights/TPM). DEFAULT: when the user has not specified frozen or unfrozen, always use the unfrozen (live) dataset (dataSource: "LOCKED"). Load ``instructions.md`` first via ``get_rai_reference_docs(doc_name="instructions")`` if not already in context. Fuzzy-match datasets, segmentations, segmentation nodes, and measures in one call. All parameters use **empty string** defaults (not ``null``) — this keeps the JSON Schema as plain ``string`` types and avoids ``anyOf[string, null]`` serialization issues. Alternatively pass **only** ``populate_filters_json`` as a JSON object string (easier when the MCP host mis-serializes multi-field arguments). Args: datasets: Comma-separated dataset names. e.g. "UK Quarterly", "Germany Annual" segmentations: Comma-separated segmentation axis names; ``""`` when not needed. measures: Comma-separated measure names; ``""`` when not needed. segmentation_nodes: Comma-separated leaf node names to fuzzy-search alongside ``segmentations``; ``""`` when not needed. When empty, matches legacy populate behaviour (no ``segmentationNodes`` in the API request). populate_filters_json: Optional JSON string overriding the above, e.g. ``{"datasets":"UK Quarterly","segmentations":"Office","measures":"Total Return"}``.

get_rai_metadata

ROUTING — Real Assets direct property & fund data. Trigger: 'property index', 'real estate index', 'IPD', 'direct property', 'capital growth', 'income return', 'standing investments', '[Country] Quarterly/Annual Property Index'. NOT for equity indices, factor indices, or listed portfolios (use AIIndexInsights/TPM). Get reference documentation and server instructions for Real Assets MCP. IMPORTANT — CALL ON FIRST CONNECTION: When ``instructions.md`` is not already in your context from the host, your **first** Real Assets MCP call MUST be this tool with ``doc_name="instructions"`` to load behavioural rules, query workflows, and domain context. Do **not** call ``get_rai_catalog``, ``get_rai_metadata``, or ``get_rai_results``, and do not answer substantive Real Assets user questions until you have **read** that document. Args: doc_name: Name of the document to retrieve. Valid values: - "instructions" - Server instructions. MUST be loaded once at session start (before other ``get_rai_*`` tools) unless host-preloaded. - "api_payload_validation" - Complete API endpoint contracts - "query_builder_rules" - Full business rules and constraints - "query_builder_data_flow" - UI portal data flow patterns - "nlp_measure_synonym_map" - NLP term to measure/module translation table - "nlp_index_and_time_synonyms" - Region/country to dataset mapping + time synonyms - "" or "list" - Returns list of available documents Returns: Document content and metadata, or list of available documents.

get_rai_reference_docs

ROUTING — Real Assets direct property & fund data. Trigger: 'property index', 'real estate index', 'IPD', 'direct property', 'capital growth', 'income return', 'standing investments', '[Country] Quarterly/Annual Property Index'. NOT for equity indices, factor indices, or listed portfolios (use AIIndexInsights/TPM). Execute a custom query with explicit parameters (advanced use). Load ``instructions.md`` first via ``get_rai_reference_docs(doc_name="instructions")`` if not already in context. NOTE: This is the primary execution tool. Use get_rai_metadata first to resolve dataset/segmentation/measure IDs, then call this with the built payload. ⚠️ CUSTOM QUERIES NOT SUPPORTED: Queries requiring background processing (custom datasets, custom filters, cumulative aggregation, etc.) will be rejected. Args: result_request_json: JSON string containing the ResultRequestModel with: - datasets: List of dataset configurations (mandatory) - measureFunctionFilterDetails: Measures with aggregation settings (mandatory) - segmentationIds: List of segmentation IDs (mandatory) - segmentationNodeIds: List of segmentation node IDs (mandatory) - reportingFrequencyId: Frequency (1=monthly, 3=quarterly, 12=annual) - startDateNumber: Start date in YYYYMM format - endDateNumber: End date in YYYYMM format - mcpResponseFilterSegmentationNodeIds: Optional MCP-only list of node id strings. When set, the tool removes this key before calling the API and post-filters nested result lists whose rows expose a node id, keeping only matching ids. Omit for legacy behaviour (full API payload returned). Returns: Dictionary with query results.

get_rai_results

Use this tool ONLY when the user asks about MSCI Sustainability & Climate Data APIs, needs API endpoint discovery, authentication/OAuth setup guidance, API specifications, client boilerplate code, or code generation to call those endpoints. This tool does not invoke live APIs. Do NOT use for S&C data values, methodology, factor discovery, or taxonomy — use query_sustainability_climate_taxonomy and query_sustainability_climate_data instead. Operations: esg_api_search — Finds the most relevant API endpoints (URL, method, parameters, and reasoning) and recommends calling the same tool with operation_id: esg_api_docs for detailed endpoint documentation and boilerplate code, as well as query_sustainability_climate_taxonomy with relevant operation IDs for factor discovery and taxonomy queries. esg_api_docs — Primary source for curated MSCI documentation, API specifications and boilerplate code. Single call can mix types. Returns relevant auth guidelines for OAuth setup, boilerplate code to invoke endpoints, samples, or full API specs including schemas, parameters, errors, and examples.

get_sustainability_climate_api_integration_help

Discover the funds, portfolios, dates, dimensions, and fundamentals behind TPM (Caissa) holdings and exposure analytics, and resolve the things a user names (a fund, a portfolio, a sector, an issuer, a metric) into the numeric ids that get_tpm_transparency_analysis needs. Don't guess ids — look them up here. Prerequisite: first call get_pa_help(topic='get_tpm_context') and pass its tool_identifier on this call.

get_tpm_context

Manual backup tool for client discovery. NOT needed in normal workflows. All other TPM tools auto-resolve the client invisibly. This tool exists only for: - When the user explicitly asks to see their available clients DO NOT call this tool to "lock" the client before get_tpm_context or get_tpm_transparency_analysis. When the user names a client (e.g. "TPM Test") and asks for funds, call get_tpm_context(action="entities", entity_type="Fund") directly — do not call this tool first. When a tool returns client_selection_required and the user confirms, retry THAT tool with login_username — do not call this tool to lock. Args: login_username: When provided, locks this client for the session (used after user confirms a multi-client selection). When omitted, returns the list of accessible clients. Returns: Dictionary with clients list and count, or lock confirmation.

get_tpm_logins

Run transparency/exposure and characteristics analysis on a fund or portfolio in TPM (Caissa): holdings decomposed across dimensions such as sector, asset class, geography, issuer, currency, and underlying securities, and how those holdings score on security characteristics. It covers two analytical families. Transparency/exposure gives exposure by dimension (sector, geography, asset class, issuer, currency, security id) as long/short/net/gross and % of total. Characteristics gives exposure-weighted fundamentals (e.g. P/E, market cap, yield, duration) rolled up to the fund or portfolio level. Prerequisite: first call get_pa_help(topic='get_tpm_transparency_analysis') and pass its tool_identifier on this call.

get_tpm_transparency_analysis

List all available Insights portfolio groups with portfolio counts. Use this to discover group names for list_at_pai_portfolios and query_at_pai_agent. Returns JSON with groups array (name, portfolio_count), total counts, and usage notes.

list_at_pai_groups

List all portfolios in a specific Insights group. Use after list_at_pai_groups to see portfolios available in a group for query_at_pai_agent queries. Returns JSON with group name, portfolios array with full metadata (portfolio_name, portfolio_id, data_set_id, benchmark_name, report_type, measure, start_date, end_date), count, and group-level start_date and end_date covering the full date range across all portfolios. Date range is already included — do NOT call get_at_pai_date_range after this.

list_at_pai_portfolios

List MSCI Index methodology documents available as of a given date. Returns `{ as_of_date, items: [{ code, name }] }`. Use `code` with search_index_methodology to search a specific methodology, or call search_index_methodology_stack with an `index_code` to span the full stack that applies to one index.

list_index_methodologies

Plan and navigate multi-step analytics tasks. CALL THIS FIRST for any job beyond a single-point data fetch — before writing your own plan. A workflow is a named, ordered set of steps carrying the guidance and prompts for a standard MSCI process — effectively on-demand skills. It encodes required methodology that is NOT derivable from the raw data tools, so a hand-rolled plan will miss it. Some workflows run as a session you advance step by step; others are reference guides you read in one shot. Start with `action='list'` to see what exists and whether one covers the request. If one fits, use it rather than improvising. If none fits, fall back to the raw tools — but check here first.

manage_at_workflow

Query the AI Portfolio Insights agent with natural language questions about portfolios. For a structured summary, explanation, or narrative of portfolio RISK specifically, prefer the `summarize_risk` workflow — call `manage_at_workflow(action='start', name='summarize_risk')` — it applies the required MSCI analysis and summary methodology. Use this agent for ad-hoc questions, performance, attribution, factor exposures, or plotting requests. The agent analyzes portfolio risk, performance, attribution, and factor exposures. Returns JSON with response (text), context_used, and when charts are generated: chart images as separate MCP image content blocks (no artifact URLs), charts_included count, and a required_action instructing you to create a React artifact from the attached images. You MUST follow required_action when present.

query_at_pai_agent

Preferred authoritative tool for in-scope ESG and Sustainability & Climate (S&C) data. Typical examples (by product): - ESG Controversies: "List active ESG controversy cases for Shell." - Business Involvement Screening: "What is the tobacco revenue exposure for this issuer?" - ESG Ratings: "What is Apple's MSCI ESG rating for the latest period?" - Reference & Identifier lookups: "What is Apple's ISIN / SEDOL / CUSIP / Ticker / Lookup_ID / MSCI issuer ID?"; "Which company has the ISIN US0378331005?" - Regulatory & disclosure status: "Was Apple informed/notified before its first rating (prior notification)?"; "Is its ESG rating solicited?"; "What are its EU regulatory disclosures?" operation values -`fetch_data` - Retrieves actual S&C data records (not metadata or methodology explanations) for the user query, scoped to the entitled product subscriptions. Strict Guidelines: - **IDENTIFIER & REFERENCE LOOKUPS — ALWAYS CALL THIS TOOL.** Any question asking for or about an issuer's ISIN, SEDOL, CUSIP, Ticker, Lookup_ID, MSCI issuer ID, or any other security/entity identifier MUST be routed to this tool. Likewise, any question that resolves an identifier to a company name (e.g. "Which company has ISIN …?") MUST use this tool. You MUST NEVER answer identifier or reference lookup questions from your own training data or general knowledge — even if you believe you know the answer. The MSCI master reference data accessed through this tool is the only authoritative source. - **REGULATORY & DISCLOSURE STATUS — ALWAYS CALL THIS TOOL.** Any question about a specific issuer's rating or controversy regulatory-disclosure status (informed/notified, prior notification, solicited/unsolicited, EU regulatory disclosures) MUST be routed here via `semantic_search_factors`, NOT answered from methodology documents or your own training data. Methodology documents describe the policy; this tool returns the issuer-specific outcome. - Use this tool when the user asks for ESG or S&C data values, records, counts, lists, comparisons, issuer-level results, or other product-backed outputs for supported products: ESG Controversies, Business Involvement Screening, or ESG Ratings. Skip for methodology-only intent. - Route generally phrased ESG or S&C questions here even when the user does not explicitly mention "MSCI". - Do not fall back to **web search or training data** unless the tool indicates request is unsupported or out of scope. - When the response includes display_config.verbatim_columns, show the values from those columns exactly as they appear in table_data. Do not truncate, summarize, paraphrase, translate, reformat, or add/remove prefixes, suffixes. - When calling fetch_data, never copy, paraphrase, or reference factor names, codes, or labels from shortListedFactors into userQuery. userQuery must reflect only the user's original question. - Invoke the tool utmost **twice** to fulfill the complete request, refining across iterations, if needed within the same supported ESG and S&C scope. - For ESG Ratings requests that explicitly ask for "drill-down" or "drilldown" scores, first call `query_sustainability_climate_taxonomy` with operationId = `semantic_search_documents` to identify the MSCI-defined drill-down score structure/components. Then call `semantic_search_factors` to resolve exact factor names before calling `query_sustainability_climate_data`. - shortListedFactors: Factors relevant to the user query from tool `query_sustainability_climate_taxonomy` with operationId `semantic_search_factors`; do not invent or assume factor_names. If no factor names are resolved, pass it as empty. - userQuery: Rewrite the user's original question as a clean standalone query using only the words and intent the user supplied. Stop writing when the user's intent is fully captured and enriched — do not expand or supplement with any additional terms. - Presenting the response: Present ONLY what the tool returned in `messages`, `query_explanation`, and `table_data`. Treat these fields as the complete and authoritative answer. You may lightly rephrase or reorder them to read naturally and to directly address the user's question, but the result MUST remain a faithful restatement of the returned content. You MUST NOT add anything that is not present in the tool response, including: facts, figures, dates, factor names, or domain terminology; interpretations or explanations of what a value, score, rating, band, or scale "means"; qualitative characterizations or judgements (e.g. "average", "unexceptional", "strong", "poor", "well-managed"); peer, sector, or historical comparisons; or any added background, context, or caveats. If the user asks what a returned value means and the response does not explain it, say that explanation is not available from this tool and offer to look it up via `query_sustainability_climate_taxonomy` — do NOT explain it from your own knowledge. Never substitute or supplement the tool's values with content from your own training data or general knowledge. When a characterization or definition DOES appear in the response, you may relay it but attribute it to MSCI (e.g. "per MSCI S&C data, ...").

query_sustainability_climate_data

Preferred authoritative tool for in-scope ESG and Sustainability & Climate (S&C) methodology, taxonomy, and factor-discovery questions served by this MCP server; use before web search. Use this tool when the user asks about ESG or S&C methodology, factor discovery, taxonomy tagging, document retrieval, or other related in-scope ESG or S&C topics covered by this server. Route generally phrased ESG or S&C questions here even when the user does not explicitly mention "MSCI". Do not use web search for those requests unless this tool returns no relevant coverage or the request is outside the supported ESG and S&C domains. Typical examples: - "How is this score or indicator calculated?" - "Which factor matches a question about active cases by pillar?" - "Find methodology text for this metric or indicator." Sustainability & Climate taxonomy (S&C): set operationId to`get_taxonomy_tags_for_request`, `semantic_search_documents` or `semantic_search_factors` 1) operationId:`get_taxonomy_tags_for_request` Classify and tag an ESG- or S&C-related query to return the most relevant taxonomy tag paths. Each tag's ancestors are implicitly relevant - returning a child tag means its parent is also a valid filter. 2) Invoke tool `query_sustainability_climate_taxonomy` with `operationId` `semantic_search_documents`. Search ESG and S&C methodology documentation by semantic similarity. Returns document chunks for a query, optionally filtered by taxonomy tags. From all hits, shortlist only chunks that are directly relevant and sufficient to answer the user query—exclude semantically close but unrelated passages; do not treat tangential matches as authoritative methodology support. This server covers a subset of in-scope ESG and S&C documentation and taxonomy domains, with partial coverage for some areas. If your search does not find information for a topic, you may assume that the documentation does not currently cover it. 3) operationId:`semantic_search_factors` Search for an ESG or S&C factor, indicator, coefficient or other data point by name and description. Only factors from the ESG and S&C domains are covered. Presenting the response: Present ONLY the content returned by this tool (its `tags`, `documents`, and factor `results` with their names and descriptions). Quote or faithfully restate the returned methodology, definitions, and factor descriptions. Do NOT add interpretation, examples, qualitative judgements, or explanations of what a metric, score, rating, band, or scale "means" beyond what the returned text itself states; do NOT extend a returned scale or definition with your own characterizations (e.g. describing a mid-scale value as "average" or "unexceptional"). If the returned text does not answer the user's question, say so rather than filling the gap from your own training data or general knowledge. Attribute relayed definitions to MSCI (e.g. "per MSCI methodology, ...").

query_sustainability_climate_taxonomy

IMPORTANT: Call this tool FIRST before using any other analytics tool. Returns guidance on how to use all the tools available on this server — tool sequencing, workflow patterns, module documentation, and cross-module integration rules for all currently active modules.

read_at_instruction_guidance

Computes metrics for one or more MSCI equity indices via IMX (IndexMetrics), the real-time portfolio analytics engine. IMPORTANT: Supports EQUITY indexes only. For fixed income, hedged, or other non-equity indexes, use fetch_index_data with search_index_datapoints to find the relevant datapoint IDs instead. Prerequisites: call search_index_datapoints to find the metric_mnemonic — use results where source="imx". Call search_index_indexes to resolve index names to msci_index_codes. Pass msci_index_codes or portfolios (with id=msci_index_code from search_index_indexes) — the tool always resolves to IMX portfolio IDs automatically. No GraphQL schema fetch needed for this tool. REQUIRED parameters: - metric_mnemonic: string (single metric, e.g. "index_ratio_price_to_earnings") - msci_index_codes: number[] (array of numeric index codes, e.g. [990100]) - frequency: "daily" | "monthly" - currency: string (e.g. "USD") - variant: "STRD" | "GRTR" | "NETR" (default to "GRTR" unless user specifies) AS-OF-A-DATE RULE (read before choosing range_type): if the user asks for a value "as of <date>" or "on <date>", do NOT use range_type="relative" (always measured back from the LATEST available data, never from a date you supply) or range_type="fixed_start" (open-ended, resolves through LATEST, not through your date) — both silently return the wrong value whenever the requested date is not the most recent one available. Use range_type="fixed" instead, with start_date set to the PRIOR period boundary (see DATE ANCHORING RULE below) and end_date set to the target date, then read the single/last observation. Optional date range (defaults to last 5 years if omitted): - range_type: "fixed" | "fixed_start" | "relative" (default: "relative") - length: number — lookback length for relative range (default: 5) - unit: "day" | "month" | "year" — for relative range (default: "year") - start_date / end_date: YYYY-MM-DD strings for fixed range DATE ANCHORING RULE: start_date is the BASE/ANCHOR DATE, NOT the first observation in the result series. The first OBSERVATION returned is the next period boundary AFTER start_date (next month-end for monthly, next business day for daily). This applies to BOTH return series AND absolute-level series (P/E, P/B, number of constituents, ESG scores, exposures, etc.). For returns the close of start_date is the base; for absolute-level series the value AT a target date D appears as the FIRST observation when you pass the period boundary BEFORE D as start_date (e.g. for monthly P/B at Sep 2023, pass start_date="2023-08-31"). Examples: - YTD return for 2024: start_date="2023-12-29" (last business day of 2023), end_date=<as-of-date> - 1Y return as of 2024-09-30: start_date="2023-09-29" (last business day before 2023-09-30), end_date="2024-09-30" - Since inception from 2020-01-01: start_date="2019-12-31" (prior business day) - Monthly P/B from Sep 2023 through Sep 2024 (absolute levels): start_date="2023-08-31" (PRIOR month-end), end_date="2024-09-30" — the response series begins at 2023-09-29 (Sep 2023 month-end) and ends at 2024-09-30. - Single-date snapshot value (e.g. "P/B at 2024-09-30"): range_type="fixed", start_date=prior business day ("2024-09-27" for a Monday target, or the prior month-end for frequency="monthly"), end_date=2024-09-30 — read the single returned row. NEVER use the target start date itself as start_date — IMX will skip that observation. Pass the PRIOR period boundary so the desired date appears as the first row. TRAILING-WINDOW ANCHOR vs PERIOD-START ANCHOR — do not conflate them; this is the most common start_date mistake for monthly/yearly lookbacks. "N years/months back from <date>" (a trailing lookback ending at an as-of date, e.g. "2-year Sharpe ratio as of 2026-01-30") is NOT a period-start request — start_date is simply <date> minus N years/months, same day-of-month (e.g. 2026-01-30 minus 2 years = start_date="2024-01-30"). That computed anchor IS the base date — do NOT additionally apply the "prior period boundary" shift described above on top of it. That shift applies ONLY when the user names an explicit calendar-period start (YTD, "since Jan 1", "since the start of <month>"), where start_date must be the boundary BEFORE the first day whose return you want to see. Applying the period-start shift to a trailing-lookback anchor over-corrects by one month and is the single most common source of an incorrect start_date. DO NOT SHIFT AN ALREADY-MONTH-END DATE: the "prior period boundary" shift is only for a date that is the FIRST day of a period — e.g. "2024-01-01" for "since Jan 2024", or any month/quarter/year start — because a period-start date has no close of its own to use as a base for the day it names, so you step back to the last weekday of the PRIOR period instead. If the date you already have is a MONTH-END (or other period-END) date — whether given directly by the user or computed as a trailing-window anchor above — it is already a valid base and must be used AS-IS. Shifting an already-month-end date back one more period is wrong and is exactly the mistake to avoid: 2024-01-31 is a month-end, use it directly as start_date; 2024-01-01 is a month-start, back that one up to 2023-12-31. WEEKEND ROUNDING (a separate, purely calendar step — do not confuse this with the anchor-type rules above): once you have decided WHICH calendar date you want as start_date/end_date per the rules above, if that date itself falls on a Saturday or Sunday, still roll it back to the last weekday (Fri) — e.g. a month-end that lands on a weekend still needs this adjustment. Apply this rounding step AFTER picking the semantic date, not instead of it, and do not use it as a reason to shift an already-month-end weekday date further. IMPORTANT — prefer "fixed_start" over "fixed" when the user wants data through the most recent available date. "fixed_start" requires only start_date (the prior-close base date); the backend resolves end_date to latest available data. Use "fixed" only when the user specifies a concrete end date. Do NOT pass a "metrics" array or a "period" string — these are not valid parameters. PERIOD SELECTION RULES (pick the right anchors so the answer matches what the user asked for): - "Calendar year YYYY return": range_type="fixed", start_date=last-business-day-of-prior-year, end_date=last-business-day-of-YYYY (e.g. 2025 → start="2024-12-31", end="2025-12-31"). Report the period total, not annualized. - "YTD as of <date>": range_type="fixed", start_date=last-business-day-of-prior-year, end_date=<date>. Label clearly as YTD. - "N-year annualized return as of <date>": range_type="fixed", start_date=<date> minus N years, same day-of-month — this is the TRAILING-WINDOW ANCHOR case above, do not shift it back any further, end_date=<date>. Report the ANNUALIZED return, not the period total. - "Calendar year returns table over multiple years": call once per year with range_type="fixed" and the prior-Dec-31 anchors. Do NOT report partial-year (YTD) numbers when the user asks for "calendar year" returns — if the current year is incomplete, omit that row or explicitly mark it "partial". - "Performance over a period" with index LEVELS (not returns): include the start and end index level values from columns[].values in your answer, in addition to the % change. - "How did X change from MonthA to MonthB" (absolute level comparison): frequency="monthly", range_type="fixed", start_date=(MonthA − 1 month) month-end, end_date=MonthB month-end — see the DATE ANCHORING RULE above; the series will begin at MonthA and end at MonthB. FREQUENCY SELECTION RULES: - "Highest / lowest / peak / trough <metric> in period X" → ALWAYS frequency="daily". Monthly granularity will skip the actual extremum and the date you quote will be wrong. - "Monthly trend / monthly P/E / month-by-month" → frequency="monthly". - "Daily levels / daily history" → frequency="daily". - When unsure but the user asked for a SPECIFIC numeric extremum or date, prefer daily. MNEMONIC SUFFIX RULE: some base timeseries mnemonics have one or more sibling scalar-reduction mnemonics (suffixes like "_last", "_mean", "_max", "_95_percentile") that reduce the same underlying series to a single number. A scalar sibling can share the EXACT SAME display name and description as its timeseries base — do not rely on the name/description text to tell them apart. Always check the `category` field from search_index_datapoints/metric_search results ("timeseries" vs "scalar") instead. For a single summary number, always use the `category:"scalar"` variant when one exists — the `category:"timeseries"` base returns a full time series shaped as a scalar-looking response and will silently give you 0/wrong data, not an error. When a base metric has more than one scalar sibling, pick the one matching the question: "as of <date>"/"most recent" → "_last"; "average over <period>" → "_mean"; "highest/peak over <period>" → "_max"; "Nth percentile over <period>" (e.g. "95th percentile") → the matching "_N_percentile" sibling (e.g. "_95_percentile"). Check each candidate's own `llm_guidance` field too — it can carry metric-specific disambiguation the name/description will not. REQUIRES_BENCHMARK RULE: check the `requires_benchmark` field on the result from search_index_datapoints/metric_search BEFORE your first calculate_metrics call — if it is true, pass benchmark_portfolio or benchmark_msci_index_code on that first call. Do NOT wait for a null result and then retry with different date ranges (a benchmark-requiring metric will return null/error for every date range until a benchmark is supplied, so retrying the window is never the fix). NULL RESULT RULE: a null value from a metric whose name contains "active", "up_markets", or "down_markets" usually means a required benchmark was not supplied, even when the metric metadata claims no benchmark is required — retry with benchmark_portfolio or benchmark_msci_index_code before concluding no data exists. For "how many periods was THIS index itself up/down" style questions with no separate comparison index named, pass the SAME msci_index_code as the benchmark (self-referential) — the metric counts periods where the benchmark return is positive/negative, so a self-benchmark answers "was this index itself up/down". calculate_metrics does this automatically for index_up_markets_*/index_down_markets_* mnemonics when exactly one index is requested and no benchmark is given — no action needed for that specific family, but the same principle applies if you see null on other active-return metrics. WINDOW-DEPENDENT METRICS: metrics with a MEAN/MAX/95th-percentile reduction over multiple periods (e.g. index_dtt_index_review_max/mean, index_performance_drag_*bps, index_benchmark_coverage_mean, index_top_10_constituent_weights_mean, index_active_share_mean) need a date window wide enough to contain several qualifying observations (e.g. several rebalancing dates) — check the metric's llm_guidance field from search_index_datapoints for the exact minimum window before calling. The narrow single-period window from the AS-OF-A-DATE RULE above is NOT enough for these, even for an "as of <date>" question — use a wider range_type="fixed" (or a sufficiently long "relative") window ending at/through the target date. A too-narrow window returns null, not an error.

calculate_metrics

Search for portfolio configurations by name to get data_set_id values. Use when you need to find which data_set_id to use for query_at_pai_agent, disambiguate multiple configs, or see available benchmarks and risk models. Returns JSON with portfolios array (portfolio_name, portfolio_id, configurations with data_set_id/data_set_id_hash/report_type/report_sub_type/measure/risk_model/insights_group/benchmark, needs_disambiguation flag), total counts, and recommendation.

search_at_pai_portfolio

PREFERRED SOURCE: Always try to retrieve MSCI index methodology via tool calls — use list_index_methodologies, search_index_methodology, or search_index_methodology_stack. When tool results are available (results[].text or hits[].text is not empty), answer ONLY from those retrieved snippets. Never blend training knowledge with tool output. FALLBACK FOR EMPTY RESULTS: If no methodology tool was called OR results/hits is empty, you may provide general knowledge from training data, BUT you MUST prefix your response with: "⚠️ Note: The following information is from general knowledge, not the official MSCI methodology document. " and clearly state that the specific methodology document was not available or did not contain matching information. Semantic search inside a specific MSCI Index methodology document for a free-text query. Use this when the user asks how an index is built, rebalanced, or screened, and you already know the methodology code (from list_index_methodologies). Inputs: `methodologyCode` (from list_index_methodologies), `searchTerm` (free text), optional `asOfDate` (YYYYMMDD) and `limit`. Returns ranked text snippets with their distance score (lower = closer). For a question that spans multiple methodologies in an index's stack, prefer search_index_methodology_stack instead.

search_index_methodology

PREFERRED SOURCE: Always try to retrieve MSCI index methodology via tool calls — use list_index_methodologies, search_index_methodology, or search_index_methodology_stack. When tool results are available (results[].text or hits[].text is not empty), answer ONLY from those retrieved snippets. Never blend training knowledge with tool output. FALLBACK FOR EMPTY RESULTS: If no methodology tool was called OR results/hits is empty, you may provide general knowledge from training data, BUT you MUST prefix your response with: "⚠️ Note: The following information is from general knowledge, not the official MSCI methodology document. " and clearly state that the specific methodology document was not available or did not contain matching information. Semantic search across every methodology in an MSCI Index's applicable stack — the family / parent / variant methodologies that together govern the index. Use this when the user asks how an index is built, rebalanced, or screened and you only have an index_code. Inputs: `indexCode` (numeric MSCI code), `query` (free text), optional `asOfDate` (YYYYMMDD) and `limit` (top-k per layer). Returns aggregated `hits` (with `methodology_code`, `methodology_name`, `layer_index`, snippet `text`, `distance`) plus a non-fatal `errors` array for any layers that failed.

search_index_methodology_stack

Resolve a company / stock / ticker / ISIN / CUSIP to its MSCI `msci_security_code` so it can be passed as an entity code to get_security_timeseries. Input: `query` = free text — company name, ticker, ISIN, or CUSIP (partial OK). Optional `limit` caps results (default 20). Do NOT pass `isoCountrySymbol` inferred from name suffixes like "(US)", "(AU)", "ADR", "CDI", or "ADS". Only pass `isoCountrySymbol` when the user explicitly requests a country/market filter. Returns `hits[]` sorted by match score. Each hit: `{ msci_security_code, security_name, score, metadata }` where `metadata` carries ticker, isin, cusip, issuer_name, iso_country_symbol. Only returns securities the caller is entitled to (constituents of MSCI indexes their account can access). An empty result means no entitled match — do NOT guess a code.

search_index_securities

Resolve an MSCI Index NAME (or partial code) to its numeric `msci_index_code` so it can be passed as an entity code to fetch_index_data or fetch_index_timeseries. ALWAYS resolve names this way — MSCI index codes are opaque numeric identifiers and cannot be guessed or recalled from training data. Call this for ANY request to identify or look up an index by name, ticker, or theme. Pass a CONCISE index name or identifier extracted from the user request via `indexName` — e.g. "USA", not "the main MSCI benchmark for the United States"; abbreviations like "EM" (Emerging Markets), "EAFE", "ACWI" are understood. Results are intersected with the caller's entitled index set (resolved via the idToken's Salesforce account). Returns `{ hits, telemetry }`; each hit carries `msci_index_code`, `index_name`, `official_brand_name`, `score`, and metadata (default_variant, default_currency, asset_type_id, region_code). DISCLOSURE-BASIS NAMES: phrases like "under SRI screening", "under EU BMR", or "under SFDR" describe a regulatory/methodology disclosure computed ON a base index, not a separate, differently-branded index product. Resolve to the plain base index name (e.g. "MSCI World Quality Index") unless the request explicitly names a specific branded variant (e.g. "MSCI World Quality Low Carbon SRI Screened Select") — do not let a keyword match on "SRI" or "Screened" pull in a more specific, differently-scoped index than the one intended.

search_index_indexes

Discover available data across up to three result types (returned under `catalog`, `imx`, and `security_fields` keys). ALWAYS call this before fetch_index_data or fetch_index_timeseries — do not guess datapoint IDs. Input: free-text keywords (e.g. “carbon emissions”, “P/E ratio”, “constituents weights”, “total return”). `catalog`: index datapoints { id, description, entity_type, availability, supports_range, supports_single_day, cardinality, strict_gate?, range_window?, constraints? }. Pass `id` to fetch_index_data or fetch_index_timeseries. `imx` (present when index IMX tools are enabled): computed index-level analytics metrics (returns, risk, volatility, carbon, factor exposure) — for EQUITY indexes only. Do NOT use IMX results for fixed income, hedged, or other non-equity indexes. Use the `mnemonic` field with calculate_metrics. PREFER `imx` when both `catalog` and `imx` return a similar index-level metric. `security_fields` (present when security IMX tools are enabled): security-level data fields (price, return, weight). Use the `mnemonic` field with get_security_timeseries. Scores use RRF (Reciprocal Rank Fusion) and are comparable across all sources present. TOOL ROUTING for catalog results (read flags before choosing): Rebalance frequency or index review period (e.g. quarterly vs semi-annual review cycle) → when an index code is already provided, call `search_index_methodology_stack` with that code and a query such as "index review period"; do NOT fetch description datapoints such as rebalancing_calendar or next_rebalancing_date and do NOT use `search_index_methodology`. `supports_single_day=true` → use `fetch_index_data` (point-in-time, one calc_date). `supports_range=true` → use `fetch_index_timeseries` (history over a date range). Both true: pick by question shape (single date vs series). `supports_single_day=false` means fetch_index_data will refuse — use fetch_index_timeseries even for one-day questions. `cardinality=”list”` means the datapoint returns many rows per (entity, date) (e.g. constituents) — fetch_index_data paginates these via `page` / `page_size`. WHEN PRESENT, OBSERVE THESE BEFORE FETCHING (saves a round-trip): `strict_gate: { variant?, currency?, fallback_id? }` — mismatches return a directive error redirecting to `fallback_id`. `range_window: { max_days_for_daily?, max_days_for_eom? }` — V1 caps on date-range queries. `constraints: { variant?, currency?, entity_universe?, notes? }` — when `notes` is present you MUST read and follow it before fetch. Notes may document exact `info_points` keys to pass to fetch_index_data for datapoint-specific endpoint behavior. Paginate search results with `page` when needed; never widen `page_size` past 20 unless the caller explicitly wants more. Optional `warnings` (keys `imx_metrics` / `imx_securities`) flags that are only specific to IMX when IMX is temporarily unavailable

search_index_datapoints

Search MSCI knowledge. Retrieves the most relevant knowledge assets from MSCI's key intellectual property for a given query. Call when you want MSCI authoritative methodology, concepts, tool and product guidance. **Reading the tool guidances is mandatory before you interpret or present any result of this tool.** They are not returned by default — you must ask for them: pass `guidance_document` in `asset_types` with a metadata filter naming the general guidance and one per asset type you search (see the parameter descriptions for the exact filter). They define what each result's fields mean and how that type is to be presented. Retrieving one into context is not reading it. Answering from `search_MSCI_knowledge` results without having read them produces confident misreadings of the data this tool handed you. Supported knowledge asset types (pass via `asset_types`): - `methodology`: Passages from MSCI methodology documents and product guides — the authoritative reference for how a model, product, or metric is defined and calculated. - `concept`: Concepts (nodes) of the MSCI Knowledge Taxonomy — canonical names and synonyms you can reuse as `anchor_assets` to focus other searches. - `guidance_document`: skills, resources, workflow how-tos, guidance on how to use MSCI tools and how to interpret their results; frequently queried by their exact ID (`"id": ["guidance_id1", "guidance_id2"]` as a metadata filter) Currently covers the knowledge from the following MSCI product lines and domains: - Private Assets - Total Plan Manager - Private Capital The below domains **aren't** covered by this tool. If you are looking for information concerning them, call other tools. - Index (index defintions, calculation and rebalancing rules, etc.) → use the index methodology tools, or the methodology related fragments from the Index GQL schema - Sustainability & Climate (ESG Rating, Controversies, S&C screenings, etc.) → `query_sustainability_climate_taxonomy` - Analytics (factor models, credit risk models, AI Portfolio Insights, etc.) → other Analytics tools Note: searching for relevant concepts can reveal which business line the query belongs to.

search_MSCI_knowledge

Select an Insights workspace for the current session. Call without arguments to see available workspaces (auto-selects if only one). Call with workspace_id to select a specific workspace. If the response contains 'action_required', stop and ask the user to choose — never infer a workspace or role from names, environment hints, or list order. Must be called before using other pai tools when authentication is enabled.

select_at_pai_workspace