MSCI Connector

Get documentation for MCP tools and modules. Returns help content aggregated from all registered modules that are published on this URL slot. Args: topic: Optional module or tool name to look up. Accepts: - None: Returns server overview with all modules and tool summaries - Module name (e.g., "pci"): Returns module overview with tool summaries - Tool name (e.g., "get_pci_user_profiles"): Returns detailed tool help Returns: Help documentation as structured data: - No argument: Server info, server tools, all modules with tool summaries - Module name: Module info with tool summaries - Tool name: Detailed help for the specific tool Example: # Get full server overview get_pa_help() # Get module overview with tool summaries get_pa_help(topic="pci") # Get detailed help for a specific tool get_pa_help(topic="get_pci_user_profiles")

get_pa_help

Get reference data needed to build valid PCI universe analytics calls. Call this before supplying analysis_end_date to get_pci_measure_detail, or when the user asks which periods are available. The Analytics API only accepts analysis end dates from a published list that grows every quarter, so the valid values cannot be assumed. Args: action: Which reference dataset to return. Each action names the data it returns; 'analysis_dates' gives the valid analysis start and end dates. Returns: For 'analysis_dates': valid_analysis_end_dates (quarter-END dates, the only accepted values for analysis_end_date), valid_analysis_start_dates (quarter-START dates), the latest end date, both counts and the read timestamp. The two lists are independent and must not be paired by position.

get_pci_analysis_context

Get universe analytics benchmarking data for private capital funds. Most measures return a single as-of-date snapshot in analysis_results. TWRR_QTD is different: it returns a QUARTERLY TIME SERIES in time_series_results. Requesting both kinds in one call returns both datasets side by side; they are not row-comparable and must not be merged. analysis_start_date and analysis_end_date bound the TWRR_QTD series only. They never change point-in-time measures. Call get_pci_analysis_context(action='analysis_dates') to pick real quarter boundaries. If this tool returns a parameter_validation_failed error, analyze the included help content to understand valid values and retry with corrected parameters. Args: measures: Comma-separated measure names (defaults to IRR if omitted) profile_guid: Profile GUID (omit to auto-select) group_by: Grouping fields (comma-separated) vehicle_type: Vehicle type filter geography: Geography filter (hierarchical paths) industry: Industry filter asset_class: Asset class filter (hierarchical paths) vintage: Vintage year filter leverage: Leverage filter (Fund vehicle only; comma-separated) seniority: Seniority filter (Fund vehicle only; comma-separated) market: Market filter (Fund of Funds only; comma-separated) min_fund_size: Minimum fund size in millions max_fund_size: Maximum fund size in millions pooled_currency: Currency for the pooled/aggregate result. Defaults to USD when omitted. 'Local' is not allowed. individual_currency: Currency for percentile/individual-fund results. Defaults to Local (each fund's own reporting currency) when omitted. analysis_start_date: YYYY-MM-DD. Earliest quarter in the TWRR_QTD series (inclusive). Time series only. Omit for full history. analysis_end_date: YYYY-MM-DD. Latest quarter in the TWRR_QTD series (inclusive). TIME SERIES ONLY -- has no effect on point-in-time measures, which always use the API's own as-of date. Returns: Dictionary with analysis_results (point-in-time measures), time_series_results (TWRR_QTD quarters), dates_applied, profile info and llm_response_footer. Each results block is present only when the corresponding measures were requested.

get_pci_measure_detail

Get PCI-enabled profiles for the authenticated user or application. An Auth0 M2M application gets the profiles linked to its BUS record, with wording for an application: it is told to pass profile_guid, not to have a user pick one. 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

Retrieves optimization job status and results. Required result_type: 'status' (poll job — queued/running/completed/failed; optional job_id), 'dates' (list rebalance dates with closing data; call before other date-based types), 'closing_portfolio' (positions/weights; requires date; optional asset_ids, as_of_date, acc_id), 'trade_suggestions' (requires date; optional acc_id), 'sleeve_assignments' | 'sleeve_transfer_suggestions' | 'sleeve_value_flow' (MULTI_SLEEVE only; requires date; optional value_type total/cash when result_type=sleeve_value_flow). Optional job_id on all types — defaults to the last submitted job in this session. While a job is running, report status and percent done to the user after each status poll.

get_qis_job_data

Retrieves the current state of the profile being built. Use this to check what has been configured and what still needs to be added, and to fetch the full ProfileRequest JSON for user-facing output (set include_full_json=true). Do not call before a profile exists (create_qis_profile_request first). Do not use instead of validate_qis_profile before presenting JSON or submitting — validation is mandatory. Do not call for API schema, workflow rules, or examples (use get_qis_reference). Avoid include_full_json=true on every intermediate check — use the default summary for progress only. On success, returns success=true with data.profile_id, data.summary (request name, simulation settings, universe/benchmark/optimization counts), data.missing_steps, data.progress_percentage, and data.full_profile only when include_full_json=true. Failures: NO_PROFILE (no profile in session), AMBIGUOUS_PROFILE (multiple profiles — pass profile_id), PROFILE_NOT_IN_CONVERSATION, GET_FAILED (API error).

get_qis_profile

Returns MSCI QIS reference material for profile authoring. Use the topic parameter: 'schema' (POCO API schema from poco-1.4.yaml; optional scope 'profile' or 'full'), 'workflow_guide' (mandatory rules, conversation flow, domain knowledge — read before creating any profile), 'examples' (list every example profile by name), or 'example' (full ProfileRequest JSON for one named example; requires example_name). Equivalent to the poco:// MCP resources for clients that don't auto-fetch resources. Do not call to read or validate the live profile (use get_qis_profile / validate_qis_profile), discover portfolio/datapoint/factor ids (use lookup_qis_data), or poll job results (use get_qis_job_data). Do not refetch topic=schema or topic=workflow_guide on every turn — call once per session unless a specific field shape is unclear. On success, returns success=true with topic-specific data: schema → data.schema (markdown) and data.scope; workflow_guide → data.guide (full static prompt); examples → data.examples [{name, description, uri}] (empty array is still success); example → data.content (ProfileRequest JSON). Failures: MISSING_PARAMETER (topic or example_name), INVALID_PARAMETER (unknown topic), EXAMPLE_NOT_FOUND (unknown example_name).

get_qis_reference

Retrieve an RCA company profile matching the website profile pages. By default this returns the Summary view only (what the website shows on first load). Request a specific section when the user asks for transactions, known holdings, mortgage debt, loan details, surveillance, or explicitly for summary, and paginate with offset/size when they ask for more rows. Three profile types are supported: - investor: buyers, sellers, owners and developers. Summary includes header, market coverage, investment activity and relationships. available_sections: summary, transactions, known_holdings, mortgage_debt. - lender: loan originators. Summary includes header, market coverage, current borrowers and financing activity. available_sections: summary, loan_details. - cmbs: CMBS issuers and deals. Summary includes header, market coverage, status snapshot and current borrowers. available_sections: summary, loan_details, surveillance. Identify the company in whichever way you already can: - master_company_id, if an earlier result or a company profile URL supplied one. Prefer this: it names the exact company. - company_name, when the user names a company and no id is known. "Blackstone", "Wells Fargo" and similar names work. The lookup uses RCA's company autocomplete and returns the best-scoring match. DO NOT search get_rca_investors or get_rca_transactions first just to find an id for a company the user has already named. Pass the name here instead. NEVER show master_company_id to the user. It is an internal RCA key. Refer to the company by name in your answer. For ranking companies by market activity across RCA, use get_rca_investors instead. For individual deals, use get_rca_transactions. Args: sort_by: Explicit sort field for investor/transactions, investor/known_holdings, investor/mortgage_debt, lender/loan_details and cmbs/loan_details. Each section has its own key list, given by get_pa_help(topic='get_rca_company_profile') and echoed in the validation error for a bad key. Omit for the section default, which matches the website. Repeat sort_by and sort_order on every page -- nothing is remembered between calls. Rejected on any other section. sort_order: asc or desc for sort_by. Defaults to desc. geography: Geography label from the section's dropdown (North America, Europe, United States; metros on tab sections where the website lists them). Omit for All Geographies. Accepted on every section whose website tab shows the dropdown: investor summary, transactions, known_holdings and mortgage_debt; lender summary and loan_details; cmbs summary, loan_details and surveillance. property_type: Full property type label (Office, Industrial, ...). Same sections as geography. Omit for All Property Types. transaction_type: Investor summary: holdings, acquisition, disposition, construction. Investor transactions: all, acquisition, disposition, refinance, construction, transfers_acq, transfers_disp. Lender and cmbs summary, where the same dropdown is the loan purpose: all, acquisition, refinance, construction. date_range: Market coverage window on the investor and lender summary (the cmbs summary has none): all_history, year_to_date, last_year, last_quarter, past_6_months, past_12_months, past_24_months, last_5_years or custom. date_range_start: ISO date with date_range=custom. date_range_end: ISO date with date_range=custom. loan_status: Loan status label. Investor mortgage_debt, lender loan_details and cmbs loan_details take this company's menu labels; the lender summary takes Outstanding or Retired. surveillance_type: cmbs surveillance only. Surveillance event type label: Construction, Sales, Troubled Property or Troubled Borrower. Omit for all types.

get_rca_company_profile

Search RCA funds, fund managers, fund investors and fund-owned assets. Use this for the fund world: vehicles, the managers running them, the investors backing them, and the properties they hold. For deals generally use get_rca_transactions; for who owns a property now use get_rca_holdings; for debt use get_rca_loans. get_rca_investors is the closest neighbour and answers a different question -- it ranks companies by market activity across all of RCA, where this ranks them by their commitments to funds. One tool, four searches. Say which you want and it is inferred: the funds themselves, the managers who run them (GP), the investors who back them (LP), or the individual properties funds hold and trade (Assets). "opportunistic funds launched since 2020" is a fund search; "which managers run the most funds" is a manager search; "pension funds investing in real estate" is an investor search; "offices funds bought in New York" is an asset search. WRITE THE QUERY FROM THE WHOLE CONVERSATION, NOT THE LAST MESSAGE. Every call is independent -- nothing is remembered between calls. If the user said "opportunistic funds" and then "only European ones", the query must carry both: "European focused opportunistic funds". Dropping earlier criteria silently widens the search and returns wrong results. Target sector, vehicle style and status, open or closed ended, stage, location focus, listed status, launch year, GAV, IRR, equity committed, fund domicile, manager headquarters, investor domicile, investor type, fund and manager names, and the property type, transaction type, price and trade date of the assets they hold can all be expressed and combined. Ordering can be expressed in the query too, with limits -- DPI, TVPI and RVPI cannot be filtered or sorted, and equity committed cannot order a search on the Funds view. For the full list and how to phrase it, call get_pa_help(topic='get_rca_funds'). Check `rejected_values` and `unsupported_filters` in the response. This search cannot report a bad filter as an error -- an unrecognised value returns no rows and an unsupported one returns everything, both looking like real answers -- so those two fields are the only way to tell a genuine empty result from a filter that never worked. Args: query: All search criteria stated so far, in plain English. mode: Optional override -- Funds, GP, LP or Assets. Omit to let the question decide, which is usually right. size: Optional page size. offset: Optional page start; pass the `next_offset` returned by a prior call to continue the same query. debug: Operator diagnostic flag. Not for normal use.

get_rca_funds

Return RCA Glossary or Methodology text as published on the website. Use for what a term means or how RCA calculates a metric. Never invent a definition when match_type is none — relay the message, say the glossary/methodology is not served for that query, and ask if the user wants an online search for a general definition.

get_rca_definitions

Search RCA property holdings and ownership using a natural language query. Holdings are current ownership records -- who owns what, right now. Use get_rca_transactions instead for deals that happened, and get_rca_investors to rank owners rather than list properties. For the fund-owned property subset use get_rca_funds in Assets mode. WRITE THE QUERY FROM THE WHOLE CONVERSATION, NOT THE LAST MESSAGE. Every call is independent -- nothing is remembered between calls. If the user said "industrial in Texas" and then "only Prologis", the query must carry both: "industrial properties in Texas owned by Prologis". Dropping earlier criteria silently widens the search and returns wrong results. Geography, property type and characteristics, owner name and owner type, hold time, income and expense, and climate risk can all be expressed and combined in the query. Ordering can be expressed in the query too, except that cap rate, DSCR and LTV are transaction and loan measures and cannot order holdings. For the full list of what can be expressed and how to phrase it, call get_pa_help(topic='get_rca_holdings'). The response includes `resolved_filters` showing exactly what was searched. Check it -- if a criterion was dropped, restate the query more explicitly rather than assuming the results are right. Args: query: All search criteria stated so far, in plain English. size: Optional page size. offset: Optional page start; pass the `next_offset` returned by a prior call to continue the same query. debug: Operator diagnostic flag. Not for normal use. sort_by: Explicit sort field, for a deterministic order instead of the natural-language-inferred one. Omit to keep today's behaviour. Holdings sort on ownership and property fields -- current_owner, last_trans_date, last_trans_price, loan_amount, lender, sf and the property-level keys -- not on price, date or cap_rate, which belong to deals. Call get_pa_help(topic='get_rca_holdings') for the full list of accepted values. sort_order: "asc" or "desc". Only meaningful with sort_by; defaults to "desc".

get_rca_holdings

Search and rank RCA investors using a natural language query. Use this to rank companies by market activity. To list the deals or properties themselves use get_rca_transactions or get_rca_holdings. WHICH SIDE OF THE MARKET YOU ASK FOR CHANGES THE ANSWER. Investors are ranked by what they did, so say it: "who bought", "who sold", "who lends", "who owns", "who develops". Say nothing and the results are the largest owners by value of holdings, which is the RCA website's own default. This is not a sort preference -- it selects a different measure entirely, so "top investors in Dallas" and "biggest buyers in Dallas" are different questions. Supported: buyers, sellers, lenders, owners, developers. WRITE THE QUERY FROM THE WHOLE CONVERSATION, NOT THE LAST MESSAGE. Every call is independent -- nothing is remembered between calls. If the user said "industrial in Texas" and then "only who bought since 2024", the query must carry both: "who bought industrial in Texas since 2024". Dropping earlier criteria silently widens the search. Geography, property type and characteristics, deal criteria such as price, cap rate, date and deal type, and investor type can all be expressed and combined in the query. For the full list of what can be expressed and how to phrase it, call get_pa_help(topic='get_rca_investors'). Two views are available. The default ranks investors by their activity. Ask for a breakdown "by property type" or "by sector" and the results are grouped that way instead. Date periods must not start or end in the future. Use completed periods or an end date of today. This applies to both views. The response reports which side of the market was used and how the ranking was measured. Check it -- if it does not match the intent, restate the query more explicitly rather than assuming the ranking is right. Args: query: All search criteria stated so far, in plain English, including which side of the market to rank by. size: Optional page size. offset: Optional page start; pass the `next_offset` returned by a prior call to continue the same query. debug: Operator diagnostic flag. Not for normal use. sort_by: Explicit sort field, for a deterministic order instead of the natural-language-inferred one. Omit to keep today's behaviour. Investment-type view only. Beware: the activity fields (holdings, acquisitions, dispositions, construction, originations) select the measure the ranking is BUILT ON, which on this view is also what selects the role -- so they change the answer, not just its order. To reorder without changing what is measured, use name, city, state, country or investor_type. Call get_pa_help(topic='get_rca_investors') for the full list. sort_order: "asc" or "desc". Only meaningful with sort_by; defaults to "desc".

get_rca_investors

Search RCA commercial real estate loans using a natural language query. Use this for loan originations and debt terms. For the sale or refinancing deal itself use get_rca_transactions; for who owns the property now use get_rca_holdings; for a ranking of the most active lenders rather than the loans themselves use get_rca_investors. WRITE THE QUERY FROM THE WHOLE CONVERSATION, NOT THE LAST MESSAGE. Every call is independent -- nothing is remembered between calls. If the user said "loans on Chicago office" and then "only floating rate", the query must carry both: "floating rate loans on Chicago office properties". Dropping earlier criteria silently widens the search and returns wrong results. Loan amount, interest rate and rate type, loan type, lender, origination and maturity dates, delinquency and distress, CMBS, geography, property type and characteristics, income and expense, climate risk, and company names can all be expressed and combined in the query. Ordering can be expressed in the query too. Be explicit about which date you mean -- origination and maturity are different filters. For the full list of what can be expressed and how to phrase it, call get_pa_help(topic='get_rca_loans'). The response includes `resolved_filters` showing exactly what was searched. Check it -- if a criterion was dropped, restate the query more explicitly rather than assuming the results are right. Args: query: All search criteria stated so far, in plain English. size: Optional page size. offset: Optional page start; pass the `next_offset` returned by a prior call to continue the same query. debug: Operator diagnostic flag. Not for normal use. sort_by: Explicit sort field, for a deterministic order instead of the natural-language-inferred one. Omit to keep today's behaviour. Lenders, borrowers and brokers cannot be sorted on. Call get_pa_help(topic='get_rca_loans') for the full list of accepted values. sort_order: "asc" or "desc". Only meaningful with sort_by; defaults to "desc".

get_rca_loans

Find the properties most comparable to one RCA property. Returns the rows of the RCA website's Peer Finder grid for the subject -- the same comparables, in the same order, with the same columns -- chosen by similarity to the subject over distance, size and construction vintage. Name the SUBJECT property in whichever way you already can: property_id or property_guid if an earlier tool call returned one, otherwise address. Do not run a transactions or holdings search first just to find an id for a property the user has already named. Peers are always the same property type as the subject, always in the same country, and always within 100 miles of it. So an empty result means no comparable transaction of that type within 100 miles inside the window -- not that the property has no comparables. Widen time_frame_months before saying anything stronger. time_frame_months counts back from today, NOT from the subject's own transaction date: a property that last traded in 2019 is still compared against the last 18 months of deals. Leave the weights at 0 -- the website's neutral default -- unless the user says what matters to them. Raise one toward 60 to make that dimension matter more, lower it toward -60 to make it matter less. At the defaults the peers are the website's opening view, closed and pending deals; any other setting also includes terminated deals, as the website does once a slider is moved. Each row carries the grid's columns. `distance` is the geographic distance from the subject, in `distance_unit`. `size` is in `size_unit` -- sf, units, or MW of IT power for a data center -- and `price_per_unit` is per that unit. `transaction_type` reads as the grid prints it ("Sale - Pending", "Terminated"), and `construction_status` replaces the years for a building that is still under construction. `rank` is the pin number the website shows: rank 1 is pin 1. Present the peers in rank order, numbered by rank, unless the user asks for another order. The website lists peers by transaction date, newest first, so rank is not a similarity order: never call rank 1 the most similar peer. There are no size, offset or sort parameters: ten peers is the whole result set, every field worth sorting by is already on each row, so re-order the peers you have rather than calling again -- a second call with different parameters would answer about a different set of peers. NEVER show property_id or property_guid to the user. Refer to each peer by its name and address.

get_rca_peerfinder

Retrieve details for one RCA property. Identify the property in whichever way you already can: - property_id or property_guid, if an earlier tool call returned one. Prefer this: it names the exact property, with no lookup. - address, when you only have a street address or a building name. "255 Greenwich St, New York", "30 St Mary Axe London" and "Empire State Building" all work. Include the city or country when you have it -- "255 Greenwich" alone matches a street in Manhattan AND one in Greenwich, Connecticut. DO NOT search holdings or transactions first just to find an id for a property you can already name. Pass the address here instead; the lookup is done for you and returns the one property. An address is matched to the property standing at that point, not to the nearest one, so a wrong or unlisted address returns no property rather than a neighbouring building. Where several properties share an address, the response lists the others alongside the details. If the result has property_name_link, use it verbatim the first time you name the property: it links the name (or address) to the property's RCA web page and keeps the URL hidden. Never print web_url, and change nothing else in the answer for the link. NEVER show property_id or property_guid to the user. They are internal RCA keys, they mean nothing to a reader, and they do not belong in a property summary. Keep them to identify the property on a follow-up call -- including the ids under other_properties_at_this_address -- and refer to the property by its name or address when you write your answer.

get_rca_property_details

Search RCA commercial real estate transactions using a natural language query. Use this for deals -- sales, refinancings, transfers and construction. For who owns a property now use get_rca_holdings; for loan originations use get_rca_loans; for ranking buyers, sellers or lenders use get_rca_investors. WRITE THE QUERY FROM THE WHOLE CONVERSATION, NOT THE LAST MESSAGE. Every call is independent -- nothing is remembered between calls. If the user said "office deals in Chicago" and then "only over $20 million", the query must carry both: "office transactions in Chicago over $20 million". Dropping earlier criteria silently widens the search and returns wrong results. Geography, property type and characteristics, price and cap rate, dates and deal type, income and expense, capital source, climate risk, and company names can all be expressed and combined in the query. Ordering can be expressed in the query too. For the full list of what can be expressed and how to phrase it, call get_pa_help(topic='get_rca_transactions'). The response includes `resolved_filters` showing exactly what was searched. Check it -- if a criterion was dropped, restate the query more explicitly rather than assuming the results are right. Args: query: All search criteria stated so far, in plain English. size: Optional page size. offset: Optional page start; pass the `next_offset` returned by a prior call to continue the same query. debug: Operator diagnostic flag. Not for normal use. sort_by: Explicit sort field, for a deterministic order instead of the natural-language-inferred one. Omit to keep today's behaviour. Call get_pa_help(topic='get_rca_transactions') for the full list of accepted values. sort_order: "asc" or "desc". Only meaningful with sort_by; defaults to "desc".

get_rca_transactions

Chart RCA TrendTracker market trend time series. Use this for how a market has moved over time: transaction volume, pricing and cap rates, sources of capital, the Commercial Property Price Index, market fundamentals, hedonic series, yield spread and liquidity scores. The other RCA tools answer about individual deals, properties, loans and companies; this one answers about the market itself, as a quarterly series going back roughly 25 years. Reach for it when the question is "what has happened to X over time" rather than "which deals". "How have LA office cap rates moved since the GFC" is this tool; "which offices sold in LA last year" is get_rca_transactions. COMPARISONS ARE ONE CALL. "Office cap rates in LA vs Manhattan" charts both as separate series -- do not call twice. Up to six series, matching the website. WRITE THE QUERY FROM THE WHOLE CONVERSATION, NOT THE LAST MESSAGE. Every call is independent. If the user said "LA office" and then "show me cap rates instead", the query must carry both. READ `amount_units` BEFORE QUOTING A NUMBER. It differs per dataset: cap rates and vacancy come back as fractions (0.0738 is 7.38%), volume as raw currency, CPPI as an index level, yield spread in basis points. They are declared rather than converted so they match the website exactly. Check `not_served`. Not every dataset exists for every geography and property type -- liquidity scores are market-level only, and some datasets need their own subscription -- so a series can be dropped while the rest succeed. Say what was left out rather than presenting a partial chart as the whole answer. Args: query: The trend to chart, in plain English, carrying all criteria stated so far. debug: Operator diagnostic flag. Not for normal use.

get_rca_trendtracker

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, or factor discovery — use search_MSCI_knowledge 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 search_MSCI_knowledge for factor discovery and methodology questions. 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

Read-only MSCI QIS discovery. Required lookup: 'portfolios' (search PAT/system portfolio ids — required currency; optional name, mds_id, vendor_id; default to NET returnType unless user specifies otherwise), 'datapoints' (list valid system datapoint ids — call before filter/rank/alpha expressions), 'risk_factors' (list or validate factor names — optional lookup_mode names or ids, default names; optional risk_model, date, factor_names, factor_ids). Factor names are model-specific and NOT guessable (GEMLTL profitability is PROFIT, not PROFITABILITY). No profile required. Do not use for OMPS user portfolios — pass OMPS ids directly in ProfileRequest JSON. Do not call for live profile state or validation (get_qis_profile / validate_qis_profile) or job results (get_qis_job_data). When the user named an index, prefer passing name for a small server-filtered response; currency-only is supported as a fallback but returns all portfolios for that currency (very large). Do not invent datapoint or factor names without calling this first. On success: lookup=portfolios → data is a JSON array of portfolio rows {name, vendorId, mdsId, currency, returnType} (mds_id-only returns one synthetic row with null name/vendorId/returnType); lookup=datapoints → data is a JSON array of datapoint id strings (empty array is success with a zero-count message); lookup=risk_factors → structured data with factor_groups, factor_count, and optional unknown_factor_names or unknown_factor_ids when validating a subset. Failures: MISSING_PARAMETER (lookup or portfolios currency), INVALID_PARAMETER, NO_RESULTS (portfolios — no matches), SEARCH_FAILED, EMPTY_RESPONSE, API_ERROR.

lookup_qis_data

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

Retrieves MSCI Sustainability & Climate (S&C) data records for issuers, securities and funds, limited to the caller's entitled product subscriptions. Returns data values, records, counts, lists, comparisons and issuer-level results. Factor definitions and methodology explanations are not returned by this tool; they are available through search_MSCI_knowledge. Covered data: - Products: ESG Ratings, ESG Controversies, Business Involvement Screening, Emissions, Climate Change Metrics, MSCI Sustainable Impact Metrics. - Reference data: ISIN, SEDOL, CUSIP, ticker, Lookup_ID and MSCI issuer ID, in both directions (identifier to issuer, issuer to identifier), from MSCI master reference data. - Issuer-level regulatory and disclosure status: prior notification, solicited/unsolicited rating status, EU regulatory disclosures. Methodology documents describe the disclosure policy; this tool returns the issuer-specific outcome. As with other data, the factor names for these fields are resolved through search_MSCI_knowledge (asset type snc_factor) before calling fetch_data. Example requests (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?" - Climate Change Metrics: "What are ExxonMobil's fossil-fuel reserves and production?"; "What is its Low Carbon Transition score?"; "What is its biodiversity footprint?" - MSCI Sustainable Impact Metrics: "What is Apple's environmental impact revenue?"; "What is its alignment with SDG 13?" - 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: - fetch_data: retrieves S&C data records for the query. Up to two fetch_data calls per request are recommended, refining the query within the same supported scope if the first result is incomplete. Inputs: - operationId: "fetch_data". - shortListedFactors: list of {factor_name, reasoning}. factor_name must be an exact identifier returned by search_MSCI_knowledge (asset type snc_factor); other names will not resolve. Include only factors directly relevant to the request, since semantically similar but unrelated factors return unrelated data. May be empty if no factors were resolved. - userQuery: the request as a standalone natural-language query, using only the words and intent the user supplied, with obvious spelling errors corrected and no added terms. Factor names, codes and labels go in shortListedFactors, not here. For follow-up questions about earlier results, include the relevant identifiers (issuer IDs, case IDs, ISINs) so the query targets the same records. Drill-down ESG Rating scores: for requests that explicitly ask for "drill-down" or "drilldown" scores, identify the MSCI-defined component structure first (search_MSCI_knowledge, asset type methodology), then resolve the exact factor names (asset type snc_factor) before calling fetch_data. Output: - messages, query_explanation, table_data: the retrieved records and a description of what was queried. Together these are the complete result. - needs_clarification: returned when an issuer name matches more than one MSCI issuer; lists the candidates. No data is returned until a specific issuer is given. - unsupported_product_ids: products in the request that are outside the caller's entitlements or the tool's coverage. - display_config.verbatim_columns: columns whose values are stored exactly as MSCI publishes them. These values are meant to be displayed as returned, without truncation, paraphrase, translation, reformatting, or added or removed prefixes and suffixes. Interpreting results: results contain only what is in messages, query_explanation and table_data. They can be rephrased or reordered for readability, as long as the restatement stays faithful to the returned content. The response does not include, and a faithful restatement does not add: - facts, figures, dates, factor names or domain terminology not present in the response; - interpretation of what a value, score, rating, band or scale means; - qualitative characterizations (e.g. "average", "unexceptional", "strong", "poor", "well-managed"); - peer, sector or historical comparisons; - background, context or caveats. MSCI ESG ratings and scores are opinions formed under MSCI's published methodology. Values from other sources are not MSCI values and should not be merged with or presented in place of MSCI values as if they were MSCI's. When a definition or characterization does appear in the response, it is MSCI's and can be attributed as such (e.g. "per MSCI S&C data, ..."). If a user asks what a returned value means without disputing it, and the response does not explain it, the explanation can be looked up through search_MSCI_knowledge. If the user is disputing the value, see Data challenges below. Data challenges: MSCI's procedure for questions that dispute a specific value is documented in the skill skill://msci-snc-insights/workflows/data-challenge-routing.md. It covers cases where a user says a value is wrong; compares it with another figure (a company disclosure, an annual report, their own analysis, a fund manager's or third party's view, or what they expected); or asks MSCI to review or correct the value or to contact the company. Retrieve it with search_MSCI_knowledge: {"asset_types": ["mcp_skill"], "metadata_filters": {"mcp_skill": {"id": ["skill://msci-snc-insights/workflows/data-challenge-routing.md"]}}} The skill is intended to be read before any view is given on whether a disputed value is right or wrong. The procedure is set out across the whole document and applies to later turns about the same value. If the skill cannot be retrieved, the correctness of an individual value cannot be assessed from this tool's output. The skill does not cover questions about what a factor measures, how a methodology works in general, missing coverage, or access and entitlement issues.

query_sustainability_climate_data

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