Morningstar

Morningstar Sustainalytics' Controversial Weapons Radar (CWR) methodology (Version 1.1, September 2024). Use this skill only when the user asks how the methodology works. Do not use this skill when the user asks which companies are involved in controversial weapons or for a specific company's involvement data (use the data/query tools for that instead). Appropriate triggers include the six covered weapon types (anti-personnel mines/landmines, biological and chemical weapons, cluster weapons/munitions, nuclear weapons, depleted uranium, white phosphorus) and their treaty basis (Ottawa Mine-Ban Treaty, BTWC, CWC, Convention on Cluster Munitions, Tlatelolco, NPT, TPNW), the Key and/or Dedicated Criteria, Main Product Type (core weapon system, supporting system, technical/administrative support), Main Activity Type, direct vs indirect involvement, ownership thresholds (10%/50% of voting rights), Categories of Involvement, involvement additions and removals, corporate actions (M&A, spin-offs, bankruptcy), issuer feedback for removal, why CWR provides no revenue figures, the fighter-jet/delivery-platform exclusion and the nuclear-triad exception, country-level convention signature data, the quarterly update cycle, and the five-step research process. Trigger even when users describe these concepts without naming them explicitly (e.g., "how does Sustainalytics decide a company is a cluster-bomb maker?", "why is this company flagged through its parent?", "are fighter jets controversial weapons?", "how does a company get off the controversial weapons list?"). Do not trigger for questions like "which companies produce landmines?" or "is company X involved in nuclear weapons?". The original PDF is bundled in `assets/` and may be served to clients on request.

controversial_weapons_radar_methodology_skill

Morningstar Sustainalytics' Controversy Ratings methodology (Version 2.0, Iteration 2, April 2026). Use this skill only when the user asks how the methodology works. Do not use this skill when the user asks for actual controversy scores, ratings, or incident data for a specific company (use the data/query tools for that instead). Appropriate triggers include controversy categories, controversy indicators, event indicators (and their descriptions), incident chains, double materiality, impact event assessment, risk event assessment, financial materiality factor, financial health risk factor, decay, severity-based weighting, Weighted Incident Chain Score (WICS), category change scenarios, methodology scope and limitations, methodological approach, research approach, company engagement, benchmarking, governance/review/market consultation, methodology revisions, Article 29b (Directive 2013/34/EU) topic mapping, EU ESG Ratings Regulation 2024/3005, ineligible incidents (e.g., contiguous territorial disputes), source eligibility, or how Sustainalytics scores ESG controversies. Trigger even when users describe these concepts without naming them explicitly (e.g., "how do you rate ESG incidents?", "explain how an oil spill turns into a controversy score", "what's the difference between impact and risk in an event", "what does Sustainalytics' weapons controversy indicator cover?"). Do not trigger for questions like "what's company X's controversy score?" or "show me incidents for Tesla". The original PDF is bundled in `assets/` and may be served to clients on request.

controversy_ratings_methodology_skill

List the research product datasets available to the current user. Returns the datasets the user has permission to access, enriched with metadata from the dataset catalog. Use the returned dataset_name values in sustainalytics_data_discovery_tool to search or list fields within a dataset. sustainalytics_exact_data_tool does not take a dataset_name — it resolves each field's dataset automatically from the udp_field_id. ## Output schema Returns a JSON string: ```json { "datasets": [ { "dataset_name": "Controversy Product Dataset", "dataset_type": null, "research_product_id": 12, "current_data": true, "historical_data": true }, { "dataset_name": "Carbon Emissions Time Series Product Dataset", "dataset_type": "time_series", "research_product_id": 70, "current_data": true, "historical_data": true } ], "count": 4 } ``` Fields: - `dataset_name` (string): pass this value as dataset_name in sustainalytics_data_discovery_tool. - `dataset_type` (string | null): null for standard datasets, "time_series" for historical time-series datasets where date ranges map to reporting years. - `research_product_id` (int): internal product identifier. - `current_data` (bool): whether the user can query current (latest) values for this dataset via sustainalytics_exact_data_tool (latest_data=true). - `historical_data` (bool): whether the user can query historical values for this dataset via sustainalytics_exact_data_tool (start_date/end_date). On error, returns `{"error": "<message>"}`.

sustainalytics_available_data_tool

Retrieve field values for one or more entities across UDP product datasets. ALWAYS use this tool whenever you already hold both entity_id(s) and udp_field_id(s) — this is the tool for that shape of input, however the IDs were obtained (a prior sustainalytics_data_discovery_tool call, a prior call to this tool, IDs supplied directly by the user, etc.). Do not re-run discovery or fall back to sustainalytics_general_data_tool once you hold numeric IDs; go straight to this tool. You do not need to know which dataset a field belongs to: pass the udp_field_id values directly and the tool resolves each one to its dataset from the field definitions and queries the right tables. ## Input schema - **entity_id_list** (`list[int]`, required): Sustainalytics entity IDs to query, e.g. `[1015763786, 1013270112]`. Duplicates are allowed but do not produce duplicate rows. - **field_id_list** (`list[int]`, required): udp_field_id values to retrieve (bigint IDs), e.g. `[181111161799, 182018442199, 181114232399]`. Each ID's dataset is resolved automatically; unknown IDs raise an error naming which ones were not recognized. Call sustainalytics_data_discovery_tool if you need to look up field IDs by name first. - **latest_data** (`bool`, default `true`): When true and no date range is given, returns only the current snapshot. Ignored (set to false) when start_date/end_date are provided. - **start_date** (`string | null`, default `null`): ISO-8601 date, e.g. `"2024-01-01"`. Must be paired with end_date. Triggers a historical Athena query. - **end_date** (`string | null`, default `null`): ISO-8601 date, e.g. `"2025-12-31"`. Must be paired with start_date. ## Routing logic | latest_data | start_date/end_date | Engine | |-------------|---------------------|--------| | true | not provided | Aurora | | (any) | provided | Athena | ## Output schema Returns a JSON string: ```json { "rows": [ { "entity_id": 1015763786, "udp_field_id": 181111161799, "udp_field_group_id": null, "valid_from": "2025-08-30", "valid_to": null, "field_value": "Some text or numeric value", "is_latest": true, "udp_field_name": "Analyst View - Overall Management Narrative" } ], "count": 31 } ``` Row fields: - `entity_id` (int): the queried entity. - `udp_field_id` (int): numeric field identifier. - `udp_field_group_id` (int | null): set for grouped/sub-rows, null otherwise. - `valid_from` (string): date the value became effective. - `valid_to` (string | null): null means still current. - `field_value` (string | null): the data point value. - `is_latest` (bool): `true` marks the current value for that field. When querying historical data, rows with `is_latest=false` are still valid results — they show the value as it stood during that period, before being superseded. For time-series datasets, one row per fiscal year has `is_latest=true`, since each year's value is independently current. - `udp_field_name` (string | null): human-readable field name (best-effort). On error, returns `{"error": "<message>"}`.

sustainalytics_exact_data_tool

Search UDP field definitions by name or look up a field directly by ID. Can also list every field belonging to a specific dataset. Accepts either a plain numeric udp_field_id for an exact lookup, or free-text for fuzzy name matching. Only fields from permitted datasets are returned. Use this to discover udp_field_id and dataset_name before calling sustainalytics_exact_data_tool, or to retrieve methodology for a known field. ## Input schema - **query** (`string`, required): Either a numeric field ID for direct lookup (e.g. `"181114232399"`), or free-text for fuzzy name search (e.g. `"carbon emissions intensity"`, `"ESG risk score momentum"`, `"overall exposure subindustry"`). Free-text handles partial words, typos, and keyword combinations. Leave empty (`""`) together with `dataset_name` to list every field in that dataset instead of searching by name. - **max_results** (`int`, default `20`): Maximum number of matches to return. Ignored for direct ID lookup and for a full dataset listing (empty `query` + `dataset_name`), both of which return every match. - **dataset_name** (`string | null`, default `null`): Optional. Exact dataset name from the catalog (see sustainalytics_available_data_tool). When set, restricts matches to that dataset; combine with an empty `query` to enumerate all of its fields rather than searching by name. ## Output schema Returns a JSON string: ```json { "query": "overall exposure score subindustry", "matches": [ { "udp_field_id": 181114232399, "udp_field_name": "Overall Exposure Score Average-Subindustry", "field_description": "...", "calculation_methodology": "...", "dataset_name": "ESG Risk Rating Product Dataset", "possible_values": "0-100", "field_type": "Numerical", "score": 95.2 } ], "count": 5 } ``` Match fields: - `udp_field_id` (int): use this in sustainalytics_exact_data_tool's field_id_list. - `udp_field_name` (string): human-readable field name. - `field_description` (string | null): description of what the field measures. - `calculation_methodology` (string | null): how the field value is calculated. Use this to answer questions like "what is the methodology for field X?". - `dataset_name` (string): the product dataset this field belongs to. Informational only — sustainalytics_exact_data_tool resolves this automatically from the udp_field_id, so you don't need to pass it. - `possible_values` (string | null): the domain of values this field can take (e.g. an enum list, a numeric range, or a category description), when defined for the field. Use this to interpret or validate `field_value` results from sustainalytics_exact_data_tool. - `field_type` (string | null): the field's catalog data type (e.g. "Numerical", "String", "Date", "Boolean"). This governs which operators sustainalytics_screening_tool accepts for the field — it can differ from what the value looks like (a 0-100 score can be typed as "String"), so check this rather than guessing from `possible_values`. - `score` (float): match confidence (0-100). Direct ID lookups and full dataset listings return 100 for every match. Fuzzy matches below 70 are excluded. On error, returns `{"error": "<message>"}`.

sustainalytics_data_discovery_tool

Expose a skill's binary asset (e.g. a methodology PDF) as a download URL. This is the binary-file branch of skill retrieval: when a `*_skill` tool lists a binary reference, it instructs you to call this tool with that asset's absolute path. The file is made downloadable via the server's `/files/{path}` route and the URL is returned. The URL is signed and short-lived (expiry noted in the result) — share it promptly; if it has expired, call this tool again for a fresh one. Only call this with a `path` handed to you verbatim by a skill tool. The server serves nothing but the assets bundled with its skills; any other path is refused. Args: path: Absolute path to a skill asset, exactly as given by the skill tool that referenced it. Returns: A string containing the download URL, size, and content type

download_file_tool

Morningstar Sustainalytics' Greenhouse Gas (GHG) Emissions methodology (Version 1.2, May 2026). Use this skill only when the user asks how the methodology works. Do not use this skill when the user asks for actual emissions data or scores for a specific company (use the data/query tools for that instead). Appropriate triggers include the Multi-Metric Multi-Factor (MMMF) Framework, GHG estimation engines, computation engines, carbon emissions estimation logic, subindustry segments, country factors, emissions data cleaning rules, the 80th percentile rule, fiscal year matching for emissions, related-entity treatment, restatements, Data Reporting Reliability Indicators (the 1–5 reliability scale), methodology scope and limitations, methodology governance/review/consultation, or how Sustainalytics computes/imputes/estimates company emissions. Trigger even when users describe these concepts without naming them explicitly (e.g., "how do you estimate Scope 3 for a company that doesn't report?", "what factors go into the carbon engine?", "how reliable is this emissions figure?", "is this number reported or estimated?"). Do not trigger for questions like "what are company X's emissions?" or "give me Scope 1 for Tesla". The original PDF is bundled in `assets/` and may be served to clients on request.

ghg_emissions_methodology_skill

All-in-one entry point for looking up companies and querying Sustainalytics data about them. ALWAYS use this tool to resolve a company to its entity ID(s) — by full or partial name, ISIN, ticker, or other identifier. NEVER guess, assume, or recall an entity_id from memory or from earlier in the conversation; entity IDs are not predictable and a wrong guess silently returns data for a different company. If you have a company name or identifier but not a verified entity_id, you MUST call this tool first. (Only use sustainalytics_exact_data_tool directly when you already hold an entity_id that THIS tool returned earlier in the same session.) Two modes, driven by whether `fields` is supplied: 1. **Company search only** — omit `fields` entirely. The tool resolves each name or identifier to its Sustainalytics entity ID and name, and stops there. Use this whenever the user only wants to identify a company, confirm coverage, or obtain an entity ID. Do NOT invent a field query just to fill the parameter. 2. **Company search + data** — supply `fields` with a plain-language description of the data point(s) wanted. The tool resolves the companies, matches your description against the research field catalogue, and returns the values. ## Batch lookups `company` accepts a list, so several companies are resolved in a single call. Pass every name/identifier the user mentioned at once rather than calling the tool repeatedly. Terms may be mixed freely — names alongside identifiers — and each is resolved independently. An identifier term (ISIN, ticker, LEI, ...) resolves to a single match; a free-text name term returns up to five candidate matches ranked by similarity. Results are grouped by the input term (see `company.matches[].input`), so you can always tell which company each match came from. When `fields` is also supplied, the data query covers every resolved entity together. ## Steps performed internally 1. Resolves each company name/identifier to its entity ID. Accepts full names ("Apple Inc"), partial names ("Apple"), ISINs ("US0378331005"), tickers ("AAPL"), and other identifier types. TIP: identifier resolution is more reliable than free-text names — if a name returns no match, retry that term with the ticker or ISIN before concluding the company is not covered. 2. *(only when `fields` is given)* Searches the field catalogue using fuzzy matching to find the relevant udp_field_id(s) and dataset(s). 3. *(only when `fields` is given)* Fetches the actual values for every resolved company. ## Input schema - **company** (`list[string]`, required): One or more company names (full or partial), ISINs, tickers, or other identifiers, e.g. `["AAPL"]` or `["Apple Inc", "Microsoft", "US0378331005"]`. A bare string is accepted and treated as a single-item list. - **fields** (`string | null`, default `null`): Optional. Plain-language description of the data you want, e.g. `"ESG Risk Rating Score"`, `"carbon emissions scope 1 2 3"`, `"overall exposure score subindustry"`. Matched against field definitions using fuzzy search. Leave unset for a pure company search. - **latest_data** (`bool`, default `true`): Return only the current values. Set to false together with a date range for historical data. - **start_date** (`string | null`, default `null`): ISO-8601 date for a historical range, e.g. `"2024-01-01"`. Must be paired with `end_date`. - **end_date** (`string | null`, default `null`): ISO-8601 date for a historical range, e.g. `"2025-12-31"`. Must be paired with `start_date`. - **max_field_results** (`int`, default `5`): Maximum number of field matches to include. Raise this when you need several related fields (e.g. all emission scopes) in one call. ## Output schema Always returns a JSON string with a consistent structure containing `company`, `fields`, and `data` keys — even when no results are found: ```json { "company": { "search_term": ["US0378331005", "Microsoft"], "matches": [ { "input": "US0378331005", "matches": [ {"entity_id": 1007903183, "name": "Apple, Inc."} ] }, { "input": "Microsoft", "matches": [ {"entity_id": 1008030982, "name": "Microsoft Corporation"}, {"entity_id": 1008030999, "name": "Microsoft Ireland Operations Ltd."} ] } ] }, "fields": { "search_term": "ESG Risk Rating Score", "matched_fields": [ { "udp_field_id": 181110101499, "udp_field_name": "ESG Risk Score-Momentum", "dataset_name": "ESG Risk Rating Product Dataset", "score": 85.2 } ] }, "data": { "rows": [ { "entity_id": 1007903183, "udp_field_id": 181110101499, "field_value": "0.5", "valid_from": "2025-01-15", "valid_to": null, "is_latest": true, "udp_field_name": "ESG Risk Score-Momentum" } ], "count": 1 }, "message": "optional informational note (only present when results are empty)" } ``` `company.search_term` echoes the list of terms searched. `company.matches` is grouped by input term: each entry has `input` (the exact search term) and `matches` (the companies it resolved to). ALWAYS use `input` to map a result back to what you asked for, and confirm each resolved `name` matches the intended company before trusting `data.rows` — the resolver may match a different or partial-name entity. An identifier term yields a single match; a free-text name term can yield several candidates (up to five, best match first), so pick the right one by name rather than assuming the first is correct. A term that resolves to nothing is absent from `matches`. If a company is missing or ambiguous, retry that term with a ticker or ISIN — an identifier resolves to exactly one company. In company-search-only mode, `fields.search_term` is `null`, `matched_fields` is empty, and `data.count` is `0` — that is the expected result, not a failure. The `message` field (string, optional) is present when a step yields no results. This is NOT an error — it means no company was found, the company is not covered by any research product, no fields matched the query, or no field query was supplied. Check `data.count` to determine whether rows were returned. On infrastructure or validation errors (e.g. query timeout, invalid date format), returns `{"error": "<message>"}` instead.

sustainalytics_general_data_tool

Morningstar Sustainalytics' Global Standards Screening (GSS) methodology (Version 1.0, Iteration 2, effective 7 April 2026). Use this skill only when the user asks how the methodology works. Do not use this skill when the user asks for a specific company's GSS assessment, watchlist status or incident data (use the data/query tools for that instead). Appropriate triggers include the Non-compliant / Watchlist / Compliant assessment categories, UN Global Compact (UNGC) Principles screening, norms-based screening, the 99 Issue Names and their mapping to the ten UNGC Principles, OECD MNE Guidelines and UN Guiding Principles (UNGPs) referencing, the two assessment dimensions (Severity of Impact and Company Management), impact factors (scale, scope, irremediability, accountability, exceptionality, negligence, duration, systematic/systemic violations), Low/Medium/High/Severe impact levels, management confidence levels, upgrade criteria and upgrade/downgrade paths, the Controversies and Standards Oversight Committee (CSOC), the GSS Outlook (12-24 month trajectory), corporate ownership rules (50%/20% thresholds, parent/subsidiary/sibling responsibility), state-owned enterprises and the Freedom House country criteria, the Controversial Weapons Radar input under Principle 2 (including the five designated nuclear weapons states rule and the arms trade framework), sanctions issues, contiguous territorial disputes (ineligible incidents), source eligibility (two-source rule, three-year recency), engagement policy, assessment validity/withdrawal, Article 29b Directive 2013/34/EU topic mapping, EU ESG Ratings Regulation 2024/3005, or methodology governance/review/market consultation/revisions. Trigger even when users describe these concepts without naming them explicitly (e.g., "why is this company non-compliant with the Global Compact?", "how does a company get off the watchlist?", "does a parent inherit its subsidiary's violation?", "how does Sustainalytics treat state-owned companies in repressive countries?"). Do not trigger for questions like "what is company X's GSS status?" or "which companies are on the watchlist?". The original PDF is bundled in `assets/` and may be served to clients on request.

global_standards_screening_methodology_skill

Documentation for this Sustainalytics UDP MCP server itself — what the server is, the full catalogue of tools it exposes (company/ESG data query tools, methodology skill tools, file download), and how the tools are meant to be used together. Use this skill when the user asks what this server or assistant can do, what tools/datasets/skills are available, which tool fits a task, how to look up a company, find a data field, or fetch historical values, or why a result looks the way it does (empty results, entity resolution, date ranges) — or to orient yourself before choosing between tools. Call with no arguments for the overview and complete tool index; load references/data-tools.md, references/methodology-skills.md, or references/utility-tools.md for parameter-level detail. Do NOT use this skill to answer actual data questions (call the data tools themselves) or questions about how a Sustainalytics methodology works (call that methodology's own skill tool) — this skill documents the server; it contains no company data and no methodology content. The running server version is 0.1.7 — answer version questions straight from this sentence, no tool call needed.

mcp_server_documentation_skill

Morningstar Sustainalytics' Product Involvement (PI) methodology (Version 2.1, May 2026). Use this skill only when the user asks how the methodology works. Do not use this skill when the user asks for a specific company's product involvement data, revenue percentages or screening results (use the data/query tools for that instead). Appropriate triggers include the six Involvement Themes (Energy, Environment, Defense & Military, Business Practices, Health, Values-based), the 28 Product Involvement Metrics and their 68 distinct types of involvement, Direct vs Indirect Involvement, business ownership rules (Controlling Interest >50%, Minority Interest 10-50%, Insignificant Interest <10%, Significant Ownership), Binary Involvement and the six binary activity classes, Revenue-based Involvement and the revenue ranges (0-4.9%, 5-9.9%, 10-24.9%, 25-49.9%, 50-100%), Capacity-based Involvement and the four capacity metrics, the reported/precise-estimation/midpoint-estimation hierarchy, non-mutually-exclusive revenues across metrics, the Most Significant Involvement (MSI) rule and scoring hierarchy, Multiple Involvements, the research process (company screening with the Crawler, metric identification, involvement type classification, level of involvement determination, information transfer), engagement, datapoint validity and timeframe (the 24-month rule), datapoint withdrawal, or methodology governance/review/market consultation/revisions. Trigger even when users describe these concepts without naming them explicitly (e.g., "how does Sustainalytics decide a company is involved in tobacco?", "what revenue share puts a company in the highest involvement bucket?", "does a parent inherit its subsidiary's gambling involvement?", "how are revenues estimated when a company doesn't disclose them?"). Do not trigger for questions like "what is company X's oil & gas involvement?" or "which companies have tobacco revenues above 5%?". Definitions, involvement types and inclusions/exclusions for each individual metric are covered by the companion Product Involvement Metric Guidelines skill. The original PDF is bundled in `assets/` and may be served to clients on request.

product_involvement_methodology_skill

Morningstar Sustainalytics' Product Involvement (PI) Metric Guidelines (client guidelines compilation, June 2026) covering all 28 Product Involvement Metrics. Use this skill when the user asks what a specific Product Involvement Metric covers or how a specific metric is defined — its definition, the business activities included or excluded, its types of involvement and Type IDs (e.g. AB1, GB3, MC5, OG7, TC5), the applicable revenue ranges or proxy per involvement type, its ESG relevance rationale, indirect involvement through ownership, or its per-metric change log. The 28 metrics are Abortion, Adult Entertainment, Alcoholic Beverages, Animal Testing, Arctic Oil & Gas Exploration, Cannabis, Contraceptives, Controversial Weapons, Fur & Specialty Leather, Gambling, Genetically Modified Plants & Seeds, Human Embryonic Stem Cells, Metallurgical Coal, Military Contracting, Nuclear Power, Oil Sands, Palm Oil, Pesticides, Pork Products, Predatory Lending, Private Prisons, Riot Control, Small Arms, Oil and Gas, Shale Energy, Thermal Coal, Tobacco Products, and Whale Meat. Trigger for questions like "what counts as gambling involvement?", "does the tobacco metric include e-cigarettes?", "which weapon types are controversial weapons?", "is trading excluded from the coal metrics?", "what is suspected involvement in animal testing?", "what does GB1 mean?". Do not use this skill when the user asks for a specific company's involvement data or screening results (use the data/query tools for that instead), and for questions about the overall Product Involvement methodology mechanics (revenue estimation hierarchy, Most Significant Involvement rule, research process, governance) prefer the companion Product Involvement Methodology skill. The original PDF is bundled in `assets/` and may be served to clients on request.

product_involvement_metric_guidelines_skill

Screen the full universe of covered entities against a filter, 10 matches at a time. Two modes, driven by which argument you pass: - **Start a new screen**: pass `filter`, omit `run_id`. - **Get the next page** of an existing screen: pass `run_id` alone (each call with the same `run_id` returns the *next* page — there is no going back to an earlier page). ALWAYS call `sustainalytics_data_discovery_tool` first to resolve each field you want to screen on to a `udp_field_id`. If discovery returns more than one plausible match, present the choices to the user and confirm before building a filter — never guess a field_id. ## Filter language `filter` is a JSON tree of leaf conditions and and/or/not groups: ```json { "op": "and", "conditions": [ {"field_id": 181114232399, "operator": "between", "value": [0, 50]}, {"op": "or", "conditions": [ {"field_id": 181111161799, "operator": "in", "value": ["A", "B"]}, {"op": "not", "conditions": [ {"field_id": 181120009911, "operator": "eq", "value": "Excluded"} ]} ]} ] } ``` A bare leaf `{"field_id": ..., "operator": ..., "value": ...}` is also a valid top-level filter on its own (no group needed for a single condition). - Group nodes: `{"op": "and" | "or" | "not", "conditions": [...]}`. `not` takes exactly one child (a leaf or a group) — wrap several conditions in an `and`/`or` first if you want to negate a combination. - Leaf nodes: `{"field_id": <int>, "operator": <str>, "value": <any>}`. - Allowed operators depend on the field's catalog type, not on what the value looks like — a field storing 0-100 scores as `String` type does NOT support `between` even though the values look numeric: - **String** fields: `eq`, `ne`, `in`, `not_in` - **Number** fields: `eq`, `ne`, `in`, `not_in`, `between` - **Date** fields: `eq`, `ne`, `between` (dates as `"YYYY-MM-DD"`) - `in`/`not_in` take a non-empty list; `between` takes a 2-element `[min, max]` list; `eq`/`ne` take a single scalar. ## Two kinds of problems 1. **A field you can't access** (unknown, inactive, or not permitted) is dropped from the filter with a warning — the rest of the screen still runs. If every referenced field is dropped this way, the screen returns zero results with a warning instead of silently matching everyone. 2. **A filter incompatible with a field's type** (wrong operator, or a value that can't match the type — e.g. text for a Number field) is a hard failure: the tool raises an error describing every problem found and **executes nothing**. Fix the filter and retry. A field's catalog `possible_values` (from `sustainalytics_data_discovery_tool`) is also checked on a best-effort basis when it parses as a clean numeric range or a short enumerated list — a value outside it produces a soft warning (the screen still runs) since `possible_values` is free text and not every field's format can be parsed reliably. ## Scope Screens the `is_latest = true` (current) data only, across whichever of your permitted datasets support current-data queries. Fields with no current value for a given entity are treated as "no data for this condition" for that entity — never assumed to pass or fail. Time-series datasets (e.g. Carbon Emissions Time Series Product Dataset) are included: they publish one `is_latest = true` row per (entity, fiscal year), since each year's value is independently current. A filter on a time-series field is evaluated against each entity's MOST RECENT fiscal year only — determined per company across the whole dataset (every field that entity reports shares the same "current" year), not per individual field. If a field has no row for an entity in that year (e.g. it lags behind the entity's other fields), that entity counts as "no data for this condition" rather than matching on an older year. Use `sustainalytics_exact_data_tool` afterward to see the entity's full fiscal-year history for a field. ## Input schema - **filter** (`object | null`): the filter tree above. Required to start a new screen; omit when paging with `run_id`. - **run_id** (`string | null`): the run to continue paging. Omit to start a new screen. Providing both `filter` and `run_id` is an error. - **page_size** (`int`, default `10`, max `50`): matches to return in this call. ## Output schema ```json { "run_id": "b3f1...-...", "page": [ { "entity_id": 1015763786, "entity_name": "Example Corp", "research_entity_id": "1015763786", "research_entity_name": "Example Corp", "fields": {"Overall Exposure Score Average-Subindustry": "42.1"} } ], "total_count": 137, "truncated": false, "has_more": true, "warnings": [] } ``` - `run_id` (string | null): pass this back to fetch the next page. Null only when nothing was accessible/executed (see problem type 1 above). - `page` (list): up to `page_size` matches. `fields` holds the values of whichever field_ids your filter referenced, keyed by field name. - `total_count` (int): total matches in this run (capped at 50,000 — see `truncated`). - `truncated` (bool): true if the run hit the 50,000-match cap. - `has_more` (bool): whether another page remains for this `run_id`. - `warnings` (list[str]): non-fatal issues (excluded fields, possible_values mismatches). Empty on later pages of the same run. Runs and their pages expire after inactivity (~30 minutes) — reusing an expired `run_id` raises an error naming it; start a new screen instead. On a genuine failure (invalid filter structure, type-incompatible filter, expired/unknown run_id, backend error), raises rather than returning a result.

sustainalytics_screening_tool