MSCI Connector

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

Query the AI Insights agent with natural language questions about portfolios. 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?" 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: - 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. - **MANDATORY: Whenever the response contains a non-empty top-level `mandatory_regulatory_disclaimer` field, you MUST append it to EVERY answer built from this tool's data, with NO exceptions.** This is a regulatory requirement, not optional formatting. Rules: 1. Output it as the LAST line of your answer, after all data, tables, and other messages. 2. Reproduce the string CHARACTER-FOR-CHARACTER. Copy the entire value exactly, including the markdown link syntax `[here](https://...)` for BOTH "here" words, so each renders as its own clickable hyperlink (two distinct links). 3. You MUST NOT rephrase, reword, summarize, translate, shorten, reformat, or "clean up" the text; MUST NOT change, encode, truncate, or swap either URL; MUST NOT drop, add, reorder, or merge the two links; MUST NOT convert the markdown links to plain text, footnotes, or a single combined link; and MUST NOT wrap it in a code block or quote. 4. Include it EXACTLY ONCE per response. Show it even when the user did not ask for disclosures and even if your answer is brief. 5. If you are unsure how to format anything else, the disclaimer still takes priority — never omit it. - 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`, `table_data`, and `mandatory_regulatory_disclaimer`. Treat these fields as the complete and authoritative answer. You may lightly rephrase or reorder `messages`, `query_explanation`, and `table_data` to read naturally and to directly address the user's question, but the result MUST remain a faithful restatement of the returned content. The `mandatory_regulatory_disclaimer` field is the ONE exception to rephrasing: it MUST be reproduced verbatim (see the dedicated `mandatory_regulatory_disclaimer` rule above) and MUST NOT be lightly rephrased, reordered, or treated as optional. 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`, factor `results` with their names and descriptions, and the `mandatory_regulatory_disclaimer`). 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, ..."). MANDATORY: Whenever the response contains a non-empty top-level `mandatory_regulatory_disclaimer` field, you MUST append it to EVERY answer built from this tool, with NO exceptions. This is a regulatory requirement, not optional formatting. Rules: 1. Output it as the LAST line of your answer, after all other content. 2. Reproduce the string CHARACTER-FOR-CHARACTER, including any markdown link syntax `[text](https://...)` so each link renders as its own clickable hyperlink. 3. You MUST NOT rephrase, reword, summarize, translate, shorten, reformat, or "clean up" the text; MUST NOT change, encode, or truncate any URL; MUST NOT change link anchor text, drop, add, reorder, or merge links; MUST NOT convert markdown links to plain text; and MUST NOT wrap it in a code block or quote. 4. Include it EXACTLY ONCE per response, even when the user did not ask for disclosures.

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

Get instructions for the current step of a multi-step workflow. Returns a progress checklist showing all workflow steps plus focused instructions for the requested step. Follow the instructions, then call this tool again with the next step ID shown in the response. The workflow is NOT complete until the response says 'WORKFLOW COMPLETE'.

run_at_workflow_step

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/risk_model/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).

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.

search_index_datapoints

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. Must be called before using other pai tools when authentication is enabled.

select_at_pai_workspace