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.
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.
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.
- 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.
Always returns a JSON string with a consistent structure containing company, fields, and data keys — even when no results are found:
{
"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.
