Resolve Entity
resolve_entity"What's the ticker for…" / "find the CIK for…" / "what's the LEI for…" / "what's the RxCUI for…" / "look up the ID for…" / "what is X's official identifier" / "who owns X" / "is X a subsidiary of Y" — resolve a user-spoken NAME to the canonical/official identifiers other tools require as input. Use FIRST whenever you have a name but need an ID. SUPPORTED TYPES: "company" (cross-source identity spine: 10-digit CIK + ticker + company_name from SEC EDGAR, legal-entity LEI from GLEIF with parent/ultimate-parent/children ownership when the LEI resolves, and security FIGI from OpenFIGI — by exact ticker map when a ticker is implied, and otherwise by name search, so NON-EQUITY instruments that never have a ticker (municipal and corporate bonds, notes, authority debt) DO resolve here; when a name matches more than one instrument it asserts nothing and returns figi_candidates to pick from, which is the correct answer to an issuer name that does not identify a single bond; every identifier is labelled with the source that established it, and an identifier that could NOT be resolved is stated explicitly under unresolved rather than omitted — accepts ticker, CIK, ISIN, or company name as input; an ISIN like "CH0038863350" resolves to the LEGAL ENTITY that issued the security via the GLEIF ISIN-to-LEI mapping, covering non-US issuers EDGAR cannot reach), "drug" (returns RxCUI + ingredient + brand from RxNorm + pipeworx://rxnorm/concept/{rxcui} citation; accepts brand or generic name). LEI/FIGI enrichment degrades gracefully — if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return. Each call cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups.
Example tool call
This call uses example arguments supplied in the tool’s input schema.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"type": "company",
"value": "AAPL"
},
"name": "resolve_entity"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | Entity type: "company" or "drug". | |
| value | Yes | For company: ticker (AAPL), CIK (0000320193), or name. For drug: brand or generic name (e.g., "ozempic", "metformin"). Pass the ENTITY NAME ONLY — for a bond that is the ISSUER exactly as printed ("NEW YORK ST DORM AUTH"), never the question's full noun phrase ("NEW YORK ST DORM AUTH revenue bonds"): the FIGI lookup matches instrument names, so trailing security-class words match nothing. | |
| country | No | OPTIONAL ISO 3166-1 alpha-2 of the country whose business register you mean ("NO", "FI", "JP", "GB", "FR", "EE", "BR"). Narrows the national-register fan-out and is often the difference between the right company and a US namesake — "Apple" with country "NO" is a Norwegian company, not Apple Inc. Omitting it searches every register we can name, which is the right default when you do not know. company only; ignored for drug. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes | Every identifier established: cik, ticker, company_name, lei, figi, isin, cusip, register_id, register_country. A key absent here appears in `unresolved` with a reason — never silently dropped. | |
| type | Yes | ||
| brand | No | ||
| notes | No | ||
| query | Yes | ||
| related | No | Entities that collapsed INTO the match, each carrying `collapsed_by`. | |
| sources | Yes | Per-identifier provenance. Every key in `ids` has a matching key here. | |
| resolved | Yes | At least one identifier was established. Read `match_status` and `unresolved` for WHICH — a company can be resolved in a national register with no CIK at all. | |
| searched | No | EVERY register asked, with its own as-of date and row count. A register that could not be reached carries `error` — 0 rows with an error is "we could not ask", 0 rows without one is "nothing is there", and they are different answers. | |
| registers | No | The matched entity as every register that carries it — the match (flagged `matched: true`) plus anything that collapsed into it. A Companies House number AND the LEI that crosswalks to it are the SAME answer, not rivals. | |
| resources | No | ||
| candidates | No | Rivals, best first. Populated on "ambiguous" and on "matched" alike. | |
| ingredient | No | ||
| unresolved | Yes | Per-identifier reason an id could NOT be established — the honest twin of `ids`. | |
| cik_withheld | No | A CIK that came back from a FUZZY SEC name match and is NOT asserted, because the spine matched a stronger non-US candidate, or `match_status` is "ambiguous" or "incomplete" and the SEC hit was not an exact ticker, CIK or legal name (fleet #3606). The number is here so a caller who wanted the US filer can still use it; what changed is that we no longer claim it IS the answer. See `unresolved.cik` for the reason. | |
| lei_withheld | No | A LEI that is NOT asserted: it matched the bare string exactly in GLEIF, but `match_status` is "ambiguous" or "incomplete" so the registers cannot say which company that string means, and a GLEIF hit on the same string is the same guess from another register. `relationships` is withheld with it. A LEI from an exact SEC hit, or from a complete legal name carrying its legal form, is never withheld. See `unresolved.lei`. | |
| match_status | No | The headline to branch on. "ambiguous" is an ANSWER, not a failure: two companies matched the name equally well and both are in `candidates`. "no_match" means every register in `searched` was asked and none carried it. "incomplete" means one of them could NOT be asked (it carries an `error` in `searched[]`), so the candidate set is short by an unknown amount and no id is asserted — distinct from "ambiguous" because a RETRY is what resolves it, not a narrower query; `fanout_incomplete` names the unreachable registers and carries, under `withheld_match`, the candidate that would have been returned on a complete fan-out. | |
| figi_withheld | No | A FIGI that is NOT asserted. Either it matched this name in OpenFIGI (`figi_match: "name_search"`) while `match_status` is "incomplete" — a name search cannot tell a company apart from a security carrying its name, and the registers that would have settled it are the ones we could not ask — or it is a `ticker_map` FIGI whose ticker came from a FUZZY SEC name match that is itself withheld (`cik_withheld`), so the mapping inherits the doubt. A `ticker_map` FIGI from an EXACT SEC hit (a real ticker, a CIK, an exact legal name) is never withheld. Carried so a caller who accepts the caveat can use it; see `unresolved.figi`. | |
| match_scoring | No | The margin rule's own inputs, so a caller can see WHY it fell where it did. | |
| ticker_withheld | No | The ticker of a FUZZY SEC name match that is NOT asserted, withheld together with `cik_withheld` because it is the same guess. Carried so a caller who meant the US filer can still use it; see `unresolved.ticker`. | |
| sec_alternatives | No | EDGAR's other name-matching candidates: distinct companies, deduped by CIK, excluding this issuer's own share classes — surfaced instead of dropped so a caller can tell a genuinely CONTESTED name match from a clean one. | |
| fanout_incomplete | No | Present IFF at least one register in `searched[]` carried an `error` — set even when `match_status` stayed "ambiguous". `withheld_match` is the candidate this call declined to ASSERT because a register was missing, carried rather than discarded so a caller who accepts the caveat can still use it. | |
| match_explanation | No | Plain words. Always present when the spine ran, and required on "ambiguous" and "no_match". | |
| company_name_withheld | No | The company name of a FUZZY SEC name match that is NOT asserted, withheld together with `cik_withheld`. See `unresolved.cik`. |