sanctions-screening-mcp-server

Screen a name (person, company, vessel, aircraft) against all loaded sanctions watchlists at once — OFAC SDN + Consolidated, EU, UK, and UN — alias- and fuzzy-aware. Returns scored potential matches with the source list, sanctioning program, designation date, and the matched alias. Strict mode (default) matches exact-normalized then all-tokens-present; fuzzy mode (or auto when strict is empty) adds Jaro-Winkler and phonetic matching and labels hits approximate with a raw 0–1 similarity score plus the count of query tokens the candidate covers, which orders candidates that tie on score. Results are paged: totalAvailable and hasMore report matches beyond the returned page, and nextOffset retrieves them. This is a screening AID for a human/compliance review, NOT a compliance determination: a hit means "review this candidate against the official source," and an empty result never means "cleared."

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "description": "The name to screen (person, organization, vessel, or aircraft), in any script. It must contain at least one letter or digit, and at most 64 words and 1024 characters."
    },
    "entityType": {
      "default": "any",
      "description": "Restrict to one entity class, or \"any\" (default) to screen across all.",
      "type": "string",
      "enum": [
        "any",
        "person",
        "organization",
        "vessel",
        "aircraft"
      ]
    },
    "matchMode": {
      "default": "strict",
      "description": "strict (default): exact-normalized then all-tokens-present. fuzzy: also scored Jaro-Winkler + phonetic. Strict auto-falls-back to fuzzy when it finds nothing.",
      "type": "string",
      "enum": [
        "strict",
        "fuzzy"
      ]
    },
    "minScore": {
      "description": "Score floor for fuzzy hits (0–1), applied uniformly to every fuzzy candidate regardless of how it was matched (Jaro-Winkler, token, or phonetic). No hit below this score is returned. Applies to fuzzy mode only; defaults to the server's configured floor.",
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "sources": {
      "description": "Restrict to specific source lists. Omit to screen all loaded lists.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "ofac_sdn",
          "ofac_consolidated",
          "eu",
          "uk",
          "un"
        ]
      }
    },
    "limit": {
      "default": 25,
      "description": "Maximum number of potential matches to return in one page.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "default": 0,
      "description": "Zero-based index of the first potential match to return. Re-call with the returned nextOffset to page through every match when hasMore is true; an offset past the end returns an empty page, not an error.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "name"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "hits": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "source": {
            "type": "string",
            "enum": [
              "ofac_sdn",
              "ofac_consolidated",
              "eu",
              "uk",
              "un"
            ],
            "description": "Which watchlist this candidate is on — its provenance."
          },
          "sourceLabel": {
            "type": "string",
            "description": "Human-readable name of the source list."
          },
          "sourceEntryId": {
            "type": "string",
            "description": "The list's own entry ID — pass to sanctions_get_designation for the full record."
          },
          "referenceNumber": {
            "description": "The list's published reference number (UN, EU, UK OFSI Group ID); absent when the list publishes none for the entry.",
            "type": "string"
          },
          "entityType": {
            "type": "string",
            "enum": [
              "person",
              "organization",
              "vessel",
              "aircraft",
              "unknown"
            ],
            "description": "Entity classification as published by the source."
          },
          "primaryName": {
            "type": "string",
            "description": "Primary published name of the designated entity."
          },
          "matchedName": {
            "type": "string",
            "description": "The specific name or alias string that matched the query."
          },
          "matchedNameType": {
            "type": "string",
            "enum": [
              "primary",
              "aka",
              "fka",
              "low-quality-aka"
            ],
            "description": "Provenance of the matched name: primary, a.k.a., f.k.a., or a low-quality a.k.a."
          },
          "matchType": {
            "type": "string",
            "enum": [
              "exact",
              "strong",
              "approximate"
            ],
            "description": "exact = normalized name equality; strong = all query tokens present; approximate = fuzzy/phonetic."
          },
          "score": {
            "description": "Raw Jaro-Winkler similarity (0–1) for approximate hits only — a real measurement, not a confidence verdict. Absent for exact/strong hits.",
            "type": "number"
          },
          "queryTokenCoverage": {
            "description": "How much of the query this candidate explains, as a literal token count — a second real measurement, never folded into score. It is the tie-break applied after score, because one shared exact token pins several candidates at the same score. Absent for exact/strong hits.",
            "type": "object",
            "properties": {
              "covered": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991,
                "description": "Query tokens individually matched by one of this candidate's tokens at the applied score floor."
              },
              "total": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991,
                "description": "Total tokens in the normalized query."
              }
            },
            "required": [
              "covered",
              "total"
            ],
            "additionalProperties": false
          },
          "program": {
            "description": "Sanctioning program / regime, when published by the source.",
            "type": "string"
          },
          "designationDate": {
            "description": "The source's own designation date as YYYY-MM-DD; absent when unpublished.",
            "type": "string"
          }
        },
        "required": [
          "source",
          "sourceLabel",
          "sourceEntryId",
          "entityType",
          "primaryName",
          "matchedName",
          "matchedNameType",
          "matchType"
        ],
        "additionalProperties": false,
        "description": "One potential match — a candidate to verify, never a determination."
      },
      "description": "Potential matches, ranked by match type, then score, then how much of the query each candidate explains."
    },
    "caveat": {
      "type": "string",
      "description": "Decision-support caveat — this is a screening aid, not a compliance determination."
    },
    "normalizedQuery": {
      "type": "string",
      "description": "The name as the server folded it for matching."
    },
    "matchModeUsed": {
      "type": "string",
      "description": "The match mode actually applied (strict may auto-upgrade to fuzzy on empty)."
    },
    "totalCount": {
      "type": "number",
      "description": "Number of potential matches returned in this page."
    },
    "totalAvailable": {
      "type": "number",
      "description": "Potential matches available across all pages, before limit and offset were applied."
    },
    "totalAvailableBasis": {
      "type": "string",
      "enum": [
        "exact",
        "lower_bound"
      ],
      "description": "How to read totalAvailable: exact = the complete strict match set; lower_bound = a bounded scan produced it (every fuzzy pass, and any strict pass that hit the raw-row scan cap), so more may exist."
    },
    "hasMore": {
      "type": "boolean",
      "description": "True when potential matches remain beyond this page — re-call with nextOffset."
    },
    "nextOffset": {
      "description": "The offset to request next. Present only when hasMore is true.",
      "type": "number"
    },
    "notice": {
      "description": "Guidance when no candidate matched — how to broaden, and what an empty result does NOT mean — or when the requested offset sits past the end of the result set.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `name_not_searchable`: The name contains no letter or digit, so nothing in it can be matched. `name_too_long`: The name is longer than 64 words or 1024 characters. `mirror_not_ready`: The sanctions mirror has never completed an initial sync. Other values are possible when a failure originates below the handler.",
              "examples": [
                "name_not_searchable",
                "name_too_long",
                "mirror_not_ready"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "hits",
        "caveat",
        "normalizedQuery",
        "matchModeUsed",
        "totalCount",
        "totalAvailable",
        "totalAvailableBasis",
        "hasMore"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Look up an identifier — a vessel IMO number, a SWIFT/BIC code, a digital-currency wallet address, a passport or national ID number, or any other identifier a list publishes — against all loaded sanctions watchlists at once: OFAC SDN + Consolidated, EU, UK, and UN. Exact match after normalization, with no fuzzy or partial matching and no score: spacing, letter case, and the separators - . / are ignored, an IMO number matches with or without its IMO prefix, a SWIFT/BIC code compares on its first eight characters so a branch code matches its institution, and a wallet address folds case only where its encoding is case-insensitive (hex, bech32, cashaddr — never base58). Returns every designation that publishes a matching identifier, one per designation, with the identifiers that matched as published; sanctions_get_designation pulls the full record. This is a screening AID for a human/compliance review, NOT a compliance determination: a hit means "review this candidate against the official source," and an empty result never means "cleared" — an identifier a list prints only in free-text remarks, or bundled with other numbers in one field, does not match.

{
  "type": "object",
  "properties": {
    "value": {
      "type": "string",
      "minLength": 1,
      "description": "The identifier to look up, as you hold it (e.g. \"IMO 7406784\", \"DCBKKPPY\", a wallet address, a passport number). Must contain at least one character other than whitespace and - . /"
    },
    "type": {
      "default": "any",
      "description": "Restrict to one identifier category, matched on the label each list publishes, or \"any\" (default) to search every published identifier, including categories with no name here (MMSI, call signs, tail numbers, tax and registration numbers, email, websites).",
      "type": "string",
      "enum": [
        "any",
        "imo",
        "swift_bic",
        "digital_currency_address",
        "passport",
        "national_id"
      ]
    },
    "sources": {
      "description": "Restrict to specific source lists. Omit to search all loaded lists.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "ofac_sdn",
          "ofac_consolidated",
          "eu",
          "uk",
          "un"
        ]
      }
    }
  },
  "required": [
    "value"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "hits": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "source": {
            "type": "string",
            "enum": [
              "ofac_sdn",
              "ofac_consolidated",
              "eu",
              "uk",
              "un"
            ],
            "description": "Which watchlist this candidate is on — its provenance."
          },
          "sourceLabel": {
            "type": "string",
            "description": "Human-readable name of the source list."
          },
          "sourceEntryId": {
            "type": "string",
            "description": "The list's own entry ID — pass to sanctions_get_designation for the full record."
          },
          "primaryName": {
            "type": "string",
            "description": "Primary published name of the designated entity."
          },
          "entityType": {
            "type": "string",
            "enum": [
              "person",
              "organization",
              "vessel",
              "aircraft",
              "unknown"
            ],
            "description": "Entity classification as published by the source."
          },
          "program": {
            "description": "Sanctioning program / regime, when published by the source.",
            "type": "string"
          },
          "matchedIdentifiers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "description": "Identifier label as the list publishes it (e.g. Vessel Registration Identification, IMO Number, SWIFT BIC, Digital Currency Address - ETH, Passport)."
                },
                "value": {
                  "type": "string",
                  "description": "Identifier value exactly as published, letter case included."
                },
                "country": {
                  "description": "Issuing country/authority, when published.",
                  "type": "string"
                }
              },
              "required": [
                "type",
                "value"
              ],
              "additionalProperties": false,
              "description": "One published identifier that matched the lookup."
            },
            "description": "Every identifier this designation publishes that matched, as published — several when the list prints one number more than one way."
          }
        },
        "required": [
          "source",
          "sourceLabel",
          "sourceEntryId",
          "primaryName",
          "entityType",
          "matchedIdentifiers"
        ],
        "additionalProperties": false,
        "description": "One designation that publishes a matching identifier — a candidate to verify."
      },
      "description": "Designations that publish a matching identifier, one per designation, ordered by source list then entry ID. Not paged — the most widely shared published identifiers map to about a dozen designations."
    },
    "caveat": {
      "type": "string",
      "description": "Decision-support caveat — this is a screening aid, not a compliance determination."
    },
    "totalCount": {
      "type": "number",
      "description": "Number of designations returned."
    },
    "notice": {
      "description": "Guidance when no designation matched — what to try next, and what an empty result does NOT mean.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `identifier_not_searchable`: The value is left with nothing to compare once whitespace and the separators - . / are removed (or, for type imo, a bare IMO prefix). `mirror_not_ready`: The sanctions mirror has never completed an initial sync. Other values are possible when a failure originates below the handler.",
              "examples": [
                "identifier_not_searchable",
                "mirror_not_ready"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "hits",
        "caveat",
        "totalCount"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Fetch the full record for one sanctions designation by source list + entry ID or the list's published reference number — the drill-in after sanctions_screen_name or sanctions_screen_identifier surfaces a candidate, or the lookup for a reference a notice cites (UN QDe.004, EU EU.27.28, UK OFSI Group ID). Returns all published aliases, identifiers (passport, national ID, tax and registration numbers, SWIFT/BIC codes, digital-currency addresses, vessel call signs, aircraft tail and serial numbers, phone numbers, email addresses, websites), addresses, dates and places of birth at the precision the source published, nationalities, sanctioning program, legal basis, and designation date. The record reflects exactly what the source published; missing fields mean the source omitted them. This is a screening aid — the designation record supports a compliance review, it is not itself a determination.

{
  "type": "object",
  "properties": {
    "source": {
      "type": "string",
      "enum": [
        "ofac_sdn",
        "ofac_consolidated",
        "eu",
        "uk",
        "un"
      ],
      "description": "Which source list the entry belongs to."
    },
    "entryId": {
      "type": "string",
      "minLength": 1,
      "description": "The source list's own entry ID (the sourceEntryId from sanctions_screen_name), or the reference number the list publishes for the entry (UN QDe.004, EU EU.27.28, UK OFSI Group ID 14196). Matched trimmed and case-insensitive, entry ID first."
    }
  },
  "required": [
    "source",
    "entryId"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "source": {
      "type": "string",
      "enum": [
        "ofac_sdn",
        "ofac_consolidated",
        "eu",
        "uk",
        "un"
      ],
      "description": "Source list the entry belongs to."
    },
    "sourceLabel": {
      "type": "string",
      "description": "Human-readable name of the source list."
    },
    "sourceEntryId": {
      "type": "string",
      "description": "The source list's own entry ID."
    },
    "referenceNumber": {
      "description": "The list's published reference number (UN, EU, UK OFSI Group ID); absent when the list publishes none for the entry. OFAC publishes none — its entry ID is its published number.",
      "type": "string"
    },
    "entityType": {
      "type": "string",
      "enum": [
        "person",
        "organization",
        "vessel",
        "aircraft",
        "unknown"
      ],
      "description": "Entity classification as published."
    },
    "primaryName": {
      "type": "string",
      "description": "Primary published name."
    },
    "program": {
      "description": "Sanctioning program / regime, when published.",
      "type": "string"
    },
    "legalBasis": {
      "description": "Statutory / regulatory basis, when published.",
      "type": "string"
    },
    "designationDate": {
      "description": "The source's own designation date as YYYY-MM-DD; absent when unpublished.",
      "type": "string"
    },
    "aliases": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Alias as published."
          },
          "nameType": {
            "type": "string",
            "enum": [
              "primary",
              "aka",
              "fka",
              "low-quality-aka"
            ],
            "description": "Alias provenance: a.k.a., f.k.a., or a low-quality a.k.a."
          }
        },
        "required": [
          "name",
          "nameType"
        ],
        "additionalProperties": false,
        "description": "One published alias."
      },
      "description": "All published aliases / name variants."
    },
    "identifiers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "Identifier category as the source labels it (e.g. Passport, National ID, SWIFT/BIC, Digital Currency Address - XBT, Phone Number, Website)."
          },
          "value": {
            "type": "string",
            "description": "Identifier value exactly as published, letter case included."
          },
          "country": {
            "description": "Issuing country/authority, when published.",
            "type": "string"
          }
        },
        "required": [
          "type",
          "value"
        ],
        "additionalProperties": false,
        "description": "One structured identifier."
      },
      "description": "Published identifiers: identity documents (passport, national ID, tax, registration) and, where the source publishes them, SWIFT/BIC codes, digital-currency addresses, vessel call signs, aircraft tail and serial numbers, phone numbers, email addresses, and websites."
    },
    "addresses": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "full": {
            "type": "string",
            "description": "Single-line rendering of the address."
          },
          "country": {
            "description": "Country, when published.",
            "type": "string"
          }
        },
        "required": [
          "full"
        ],
        "additionalProperties": false,
        "description": "One published address."
      },
      "description": "Published addresses."
    },
    "datesOfBirth": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "date": {
            "description": "Date of birth in ISO 8601 at the precision the source published: YYYY-MM-DD, YYYY-MM, or YYYY. A range is an interval whose ends keep their own precision (1955/1957); an open end is .. (../1980). A value with no ISO form is kept as published.",
            "type": "string"
          },
          "circa": {
            "description": "Present when the source flags the date as approximate; never without date.",
            "type": "boolean",
            "const": true
          },
          "place": {
            "description": "Place of birth, when published.",
            "type": "string"
          }
        },
        "additionalProperties": false,
        "description": "One date/place of birth."
      },
      "description": "Published dates and places of birth (persons)."
    },
    "nationalities": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Published nationalities / citizenships."
    },
    "remarks": {
      "description": "Free-form remarks published by the source, when present.",
      "type": "string"
    },
    "caveat": {
      "type": "string",
      "description": "Decision-support caveat — this is a screening aid, not a compliance determination."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `designation_not_found`: No designation in the given source has that entry ID or reference number in the mirror. `reference_ambiguous`: The entry ID is a reference number more than one designation in the source publishes. `mirror_not_ready`: The sanctions mirror has never completed an initial sync. Other values are possible when a failure originates below the handler.",
              "examples": [
                "designation_not_found",
                "reference_ambiguous",
                "mirror_not_ready"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "source",
        "sourceLabel",
        "sourceEntryId",
        "entityType",
        "primaryName",
        "aliases",
        "identifiers",
        "addresses",
        "datesOfBirth",
        "nationalities",
        "caveat"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

List the sanctions watchlists (OFAC SDN + Consolidated, EU, UK, UN) and GLEIF datasets currently loaded in the local mirror, each with its record count, source URL, license, and the mirror's readiness and as-of timestamp — for GLEIF, also whether its reporting exceptions are loaded and how many. Use this for provenance and freshness on any result — results are only as current as the last mirror refresh, and a not-ready mirror means screening cannot run yet. Attribution: UK data is under the Open Government Licence v3.0; all sources are cited here.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "sanctionsReady": {
      "type": "boolean",
      "description": "True once the sanctions mirror has completed at least one full sync."
    },
    "sanctionsAsOf": {
      "description": "ISO 8601 timestamp of the last completed sanctions sync, when available.",
      "type": "string"
    },
    "leiReady": {
      "type": "boolean",
      "description": "True once the GLEIF (LEI) mirror has completed at least one full sync."
    },
    "leiAsOf": {
      "description": "ISO 8601 timestamp of the last completed GLEIF sync, when available.",
      "type": "string"
    },
    "reportingExceptionsLoaded": {
      "type": "boolean",
      "description": "Whether GLEIF reporting exceptions are loaded. When false, sanctions_trace_ownership reads a parent level with no published relationship as unknown."
    },
    "sources": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Source code (ofac_sdn, eu, …, or gleif)."
          },
          "label": {
            "type": "string",
            "description": "Human-readable source name."
          },
          "recordCount": {
            "type": "number",
            "description": "Records currently loaded for this source (Level 1 entities for gleif)."
          },
          "reportingExceptionCount": {
            "description": "GLEIF reporting-exception records loaded (gleif only). Absent when the dataset has never been loaded — never read as zero.",
            "type": "number"
          },
          "url": {
            "type": "string",
            "description": "Upstream source URL the mirror harvests from."
          },
          "license": {
            "type": "string",
            "description": "Redistribution license / terms for this source."
          }
        },
        "required": [
          "code",
          "label",
          "recordCount",
          "url",
          "license"
        ],
        "additionalProperties": false,
        "description": "One loaded source with count, provenance, and license."
      },
      "description": "All loaded sources, sanctions lists then the GLEIF dataset."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode."
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "sanctionsReady",
        "leiReady",
        "reportingExceptionsLoaded",
        "sources"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Resolve a company or organization name (with an optional jurisdiction: a country code, which includes its subdivisions, or an ISO 3166-2 subdivision code) to candidate GLEIF Legal Entity Identifiers (LEIs), ranked. This turns a free-text counterparty name into a stable global identifier that sanctions_get_entity and sanctions_trace_ownership key off. Every name GLEIF publishes takes part: the legal name, previous legal names, trading names, alternative-language legal names, and ASCII transliterations of a legal name in another script — each candidate reports the name it matched on and that name's type, one candidate per LEI. Strict mode (default) matches exact-normalized then all-tokens-present; fuzzy mode (or auto when strict is empty) adds Jaro-Winkler scoring labeled approximate with a raw 0–1 score plus the count of query tokens the matched name covers, which orders candidates that tie on score. Results are paged: totalAvailable and hasMore report candidates beyond the returned page, and nextOffset retrieves them. Returns potential matches to confirm against the GLEIF record — name resolution is a candidate ranking, not an authoritative identification.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "description": "The company / organization name to resolve to an LEI, in any script. It must contain at least one letter or digit, and at most 64 words and 1024 characters."
    },
    "jurisdiction": {
      "description": "Optional legal-jurisdiction filter. A country code (\"US\") matches that country and every subdivision under it (US-DE, US-CA); a subdivision code (\"US-DE\") matches exactly. Case-insensitive. Empty string disables it.",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "pattern": "^[A-Za-z]{2}(-[A-Za-z0-9]{1,3})?$",
          "description": "ISO 3166-1 alpha-2 country code (e.g. US) or ISO 3166-2 subdivision code (e.g. US-DE), case-insensitive."
        }
      ]
    },
    "matchMode": {
      "default": "strict",
      "description": "strict (default): exact then all-tokens-present. fuzzy: also scored Jaro-Winkler.",
      "type": "string",
      "enum": [
        "strict",
        "fuzzy"
      ]
    },
    "status": {
      "default": "issued",
      "description": "Registration status filter. issued (default) matches ISSUED; lapsed matches exactly LAPSED; any applies no filter and is the only value that reaches the other states (RETIRED, DUPLICATE, ANNULLED, PENDING_TRANSFER, PENDING_ARCHIVAL, MERGED) — each candidate's status field names its state.",
      "type": "string",
      "enum": [
        "any",
        "issued",
        "lapsed"
      ]
    },
    "minScore": {
      "description": "Jaro-Winkler floor for fuzzy hits (0–1); defaults to the server's configured floor.",
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "limit": {
      "default": 10,
      "description": "Maximum LEI candidates to return in one page.",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "offset": {
      "default": 0,
      "description": "Zero-based index of the first LEI candidate to return. Re-call with the returned nextOffset to page through every candidate when hasMore is true; an offset past the end returns an empty page, not an error.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "name"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "matches": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "lei": {
            "type": "string",
            "description": "20-character GLEIF Legal Entity Identifier."
          },
          "legalName": {
            "type": "string",
            "description": "Registered legal name of the entity."
          },
          "matchedName": {
            "type": "string",
            "description": "The name that matched the query — the legal name or one of the other or transliterated names GLEIF publishes for the entity."
          },
          "matchedNameType": {
            "type": "string",
            "description": "Type of matchedName: LEGAL_NAME, PREVIOUS_LEGAL_NAME (a former legal name, not the current one), TRADING_OR_OPERATING_NAME, ALTERNATIVE_LANGUAGE_LEGAL_NAME, PREFERRED_ASCII_TRANSLITERATED_LEGAL_NAME, AUTO_ASCII_TRANSLITERATED_LEGAL_NAME, or UNKNOWN for a name the mirror stored without GLEIF's type."
          },
          "matchType": {
            "type": "string",
            "enum": [
              "exact",
              "strong",
              "approximate"
            ],
            "description": "exact = normalized equality; strong = all tokens present; approximate = fuzzy."
          },
          "score": {
            "description": "Raw Jaro-Winkler similarity (0–1) for approximate hits only — a real measurement.",
            "type": "number"
          },
          "queryTokenCoverage": {
            "description": "How much of the query the matched name explains, as a literal token count — a second real measurement, never folded into score. It is the tie-break applied after score, because one shared exact token pins several candidates at the same score. Absent for exact/strong matches.",
            "type": "object",
            "properties": {
              "covered": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991,
                "description": "Query tokens individually matched by one of the matched name's tokens at the applied score floor."
              },
              "total": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991,
                "description": "Total tokens in the normalized query."
              }
            },
            "required": [
              "covered",
              "total"
            ],
            "additionalProperties": false
          },
          "jurisdiction": {
            "description": "Legal jurisdiction (ISO code), when published.",
            "type": "string"
          },
          "status": {
            "description": "Registration status (e.g. ISSUED, LAPSED).",
            "type": "string"
          }
        },
        "required": [
          "lei",
          "legalName",
          "matchedName",
          "matchedNameType",
          "matchType"
        ],
        "additionalProperties": false,
        "description": "One LEI candidate — confirm against the GLEIF record before relying on it."
      },
      "description": "LEI candidates, ranked by match type, then score, then how much of the query each matched name explains."
    },
    "normalizedQuery": {
      "type": "string",
      "description": "The name as the server folded it for matching."
    },
    "matchModeUsed": {
      "type": "string",
      "description": "The match mode actually applied (strict may upgrade to fuzzy)."
    },
    "totalCount": {
      "type": "number",
      "description": "Number of LEI candidates returned in this page."
    },
    "totalAvailable": {
      "type": "number",
      "description": "LEI candidates available across all pages, before limit and offset were applied."
    },
    "totalAvailableBasis": {
      "type": "string",
      "enum": [
        "exact",
        "lower_bound"
      ],
      "description": "How to read totalAvailable: exact = the complete strict candidate set; lower_bound = a bounded scan produced it (every fuzzy pass, and any strict pass that hit the raw-row scan cap), so more may exist."
    },
    "hasMore": {
      "type": "boolean",
      "description": "True when LEI candidates remain beyond this page — re-call with nextOffset."
    },
    "nextOffset": {
      "description": "The offset to request next. Present only when hasMore is true.",
      "type": "number"
    },
    "notice": {
      "description": "Guidance when no LEI matched and how to broaden, when the requested offset sits past the end of the result set, or when the mirror has not indexed GLEIF's other and transliterated names yet, so only legal names were searched.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `name_not_searchable`: The name contains no letter or digit, so nothing in it can be matched. `name_too_long`: The name is longer than 64 words or 1024 characters. `mirror_not_ready`: The GLEIF (LEI) mirror has never completed an initial sync. Other values are possible when a failure originates below the handler.",
              "examples": [
                "name_not_searchable",
                "name_too_long",
                "mirror_not_ready"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "matches",
        "normalizedQuery",
        "matchModeUsed",
        "totalCount",
        "totalAvailable",
        "totalAvailableBasis",
        "hasMore"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Fetch the full GLEIF Level 1 record for one LEI: legal name, other/trading names, legal and headquarters addresses, registration status, jurisdiction, registration authority and ID, and last-update date — plus any sanctions hits screened against the same legal name across all loaded watchlists. The screening cross-reference is a screening AID: a hit is a candidate to verify against the official source, and no hit is not a clearance. screeningStatus says whether that cross-reference actually ran — an empty sanctionsHits under not_ready means the sanctions mirror was unavailable, not that nothing matched. sanctionsScreen says whether the hit list is the whole set: it reports how many potential matches existed before the cap, so a capped cross-reference is distinguishable from a complete one. LEI must be a 20-character GLEIF identifier (18 alphanumerics + 2 check digits).

{
  "type": "object",
  "properties": {
    "lei": {
      "type": "string",
      "pattern": "^[A-Z0-9]{18}[0-9]{2}$",
      "description": "The 20-character GLEIF Legal Entity Identifier to look up."
    }
  },
  "required": [
    "lei"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "lei": {
      "type": "string",
      "description": "The 20-character GLEIF Legal Entity Identifier."
    },
    "legalName": {
      "type": "string",
      "description": "Registered legal name."
    },
    "otherNames": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Other names published in the LEI record (trading, previous, and alternative-language legal names), as plain strings."
    },
    "alternateNames": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "The name as published."
          },
          "type": {
            "type": "string",
            "description": "GLEIF name type: PREVIOUS_LEGAL_NAME (a former legal name, not the current one), TRADING_OR_OPERATING_NAME, ALTERNATIVE_LANGUAGE_LEGAL_NAME, PREFERRED_ASCII_TRANSLITERATED_LEGAL_NAME, AUTO_ASCII_TRANSLITERATED_LEGAL_NAME, or UNKNOWN for a name the mirror stored without GLEIF's type."
          }
        },
        "required": [
          "name",
          "type"
        ],
        "additionalProperties": false,
        "description": "One name GLEIF publishes beside the legal name."
      },
      "description": "Every other and transliterated name with its type, in the order published — the typed view of otherNames plus the ASCII transliterations of a legal name in another script."
    },
    "jurisdiction": {
      "description": "Legal jurisdiction (ISO code), when published.",
      "type": "string"
    },
    "status": {
      "description": "Registration status (e.g. ISSUED, LAPSED).",
      "type": "string"
    },
    "legalAddress": {
      "description": "Single-line legal address, when published.",
      "type": "string"
    },
    "headquartersAddress": {
      "description": "Single-line headquarters address, when published.",
      "type": "string"
    },
    "registrationAuthorityId": {
      "description": "Registration authority (RA) code, when published.",
      "type": "string"
    },
    "registrationAuthorityEntityId": {
      "description": "The entity's ID at its registration authority, when published.",
      "type": "string"
    },
    "lastUpdate": {
      "description": "ISO 8601 last-update timestamp from the LEI record.",
      "type": "string"
    },
    "sanctionsHits": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "source": {
            "type": "string",
            "enum": [
              "ofac_sdn",
              "ofac_consolidated",
              "eu",
              "uk",
              "un"
            ],
            "description": "Watchlist the candidate is on."
          },
          "sourceLabel": {
            "type": "string",
            "description": "Human-readable source list name."
          },
          "sourceEntryId": {
            "type": "string",
            "description": "Source entry ID — pass to sanctions_get_designation."
          },
          "primaryName": {
            "type": "string",
            "description": "Primary published name of the designation."
          },
          "matchedName": {
            "type": "string",
            "description": "The name/alias that matched the entity's legal name."
          },
          "matchType": {
            "type": "string",
            "enum": [
              "exact",
              "strong",
              "approximate"
            ],
            "description": "exact / strong / approximate match classification."
          },
          "score": {
            "description": "Raw Jaro-Winkler similarity (0–1) for approximate hits only.",
            "type": "number"
          }
        },
        "required": [
          "source",
          "sourceLabel",
          "sourceEntryId",
          "primaryName",
          "matchedName",
          "matchType"
        ],
        "additionalProperties": false,
        "description": "A potential watchlist match on the entity's legal name — verify, do not assume."
      },
      "description": "Sanctions screening cross-reference on the entity's legal name."
    },
    "sanctionsScreen": {
      "description": "Disclosure for the cross-reference screen: how many potential matches existed before the cap, and whether sanctionsHits is the complete set. Present only when screeningStatus is 'screened'.",
      "type": "object",
      "properties": {
        "totalAvailable": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "Potential matches the cross-reference screen found before the cap was applied."
        },
        "totalAvailableBasis": {
          "type": "string",
          "enum": [
            "exact",
            "lower_bound"
          ],
          "description": "How to read totalAvailable: exact = the complete strict match set for this legal name; lower_bound = a bounded scan produced it, so more may exist."
        },
        "hasMore": {
          "type": "boolean",
          "description": "True when the potential matches were capped — screen the legal name with sanctions_screen_name to page through the rest."
        }
      },
      "required": [
        "totalAvailable",
        "totalAvailableBasis",
        "hasMore"
      ],
      "additionalProperties": false
    },
    "screeningStatus": {
      "type": "string",
      "enum": [
        "screened",
        "not_ready"
      ],
      "description": "Whether the cross-reference ran: screened = the legal name was screened against every loaded watchlist; not_ready = the sanctions mirror has never synced, so no screening ran and the empty sanctionsHits says nothing about this entity. Read sanctionsHits only when this is 'screened'."
    },
    "caveat": {
      "type": "string",
      "description": "Decision-support caveat — the screening cross-reference is an aid, not a determination."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `lei_not_found`: No GLEIF entity exists for the given LEI in the mirror. `mirror_not_ready`: The GLEIF (LEI) mirror has never completed an initial sync. Other values are possible when a failure originates below the handler.",
              "examples": [
                "lei_not_found",
                "mirror_not_ready"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "lei",
        "legalName",
        "otherNames",
        "alternateNames",
        "sanctionsHits",
        "screeningStatus",
        "caveat"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Trace the GLEIF Level 2 corporate-ownership graph for an LEI: direct and ultimate parents and/or children, traversed breadth-first to a bounded depth, with relationship type for each edge. Set screenNodes to also screen every entity in the graph against all loaded watchlists — resolving "is anyone in this ownership chain sanctioned." Each per-node screen is a screening AID: hits are candidates to verify, and an empty result for a node is not a clearance of that node. Each node whose parents were walked carries parentStatus for its direct and ultimate parent: a published relationship, a reporting exception with the reasons the entity gave (such as NATURAL_PERSONS or NON_CONSOLIDATING), none, or unknown when reporting exceptions are not loaded. The response says what it could not do: complete/truncated/missingEntityLeis report whether the loaded relationship graph within the depth is fully shown, screeningStatus reports whether the cross-reference actually ran, and each screened node reports whether its own hit list was capped. Requires a valid 20-character LEI (use sanctions_resolve_entity to obtain one).

{
  "type": "object",
  "properties": {
    "lei": {
      "type": "string",
      "pattern": "^[A-Z0-9]{18}[0-9]{2}$",
      "description": "The 20-character GLEIF LEI at the root of the ownership graph."
    },
    "direction": {
      "default": "both",
      "description": "Walk parents (who owns it), children (what it owns), or both (default).",
      "type": "string",
      "enum": [
        "parents",
        "children",
        "both"
      ]
    },
    "depth": {
      "default": 3,
      "description": "Maximum traversal depth from the root entity (1–5).",
      "type": "integer",
      "minimum": 1,
      "maximum": 5
    },
    "screenNodes": {
      "default": false,
      "description": "When true, screen every node's legal name against all watchlists — the ownership-chain cross-reference.",
      "type": "boolean"
    }
  },
  "required": [
    "lei"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "rootLei": {
      "type": "string",
      "description": "The LEI the traversal started from."
    },
    "nodes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "lei": {
            "type": "string",
            "description": "The node's LEI."
          },
          "legalName": {
            "type": "string",
            "description": "The node's legal name (the LEI itself if not hydrated)."
          },
          "jurisdiction": {
            "description": "Jurisdiction (ISO code), when known.",
            "type": "string"
          },
          "status": {
            "description": "GLEIF registration status, when known.",
            "type": "string"
          },
          "depth": {
            "type": "number",
            "description": "Breadth-first depth from the root (root = 0)."
          },
          "role": {
            "type": "string",
            "enum": [
              "root",
              "parent",
              "child"
            ],
            "description": "Position relative to the traversal."
          },
          "parentStatus": {
            "description": "What GLEIF publishes about this node's direct and ultimate accounting-consolidation parents. Present only on nodes whose parents the traversal read — every node short of the depth limit when direction is parents or both; absent on a children walk.",
            "type": "object",
            "properties": {
              "direct": {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": [
                      "relationship",
                      "exception",
                      "none",
                      "unknown"
                    ],
                    "description": "relationship = a Level 2 relationship at this level is published (see edges); exception = the entity filed a GLEIF reporting exception instead of naming this parent; none = GLEIF publishes neither; unknown = no relationship is published and reporting exceptions are not loaded in the mirror, so whether one was filed is unknown."
                  },
                  "exceptionReasons": {
                    "description": "Every reason given in the reporting exception (e.g. NATURAL_PERSONS, NON_CONSOLIDATING, NO_KNOWN_PERSON). Present only when status is exception.",
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                },
                "required": [
                  "status"
                ],
                "additionalProperties": false,
                "description": "What GLEIF publishes about the direct parent."
              },
              "ultimate": {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": [
                      "relationship",
                      "exception",
                      "none",
                      "unknown"
                    ],
                    "description": "relationship = a Level 2 relationship at this level is published (see edges); exception = the entity filed a GLEIF reporting exception instead of naming this parent; none = GLEIF publishes neither; unknown = no relationship is published and reporting exceptions are not loaded in the mirror, so whether one was filed is unknown."
                  },
                  "exceptionReasons": {
                    "description": "Every reason given in the reporting exception (e.g. NATURAL_PERSONS, NON_CONSOLIDATING, NO_KNOWN_PERSON). Present only when status is exception.",
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                },
                "required": [
                  "status"
                ],
                "additionalProperties": false,
                "description": "What GLEIF publishes about the ultimate parent."
              }
            },
            "required": [
              "direct",
              "ultimate"
            ],
            "additionalProperties": false
          },
          "sanctionsScreen": {
            "description": "Disclosure for this node's cross-reference screen: how many potential matches existed before the per-node cap, and whether sanctionsHits is the complete set. Present only when the node was screened.",
            "type": "object",
            "properties": {
              "totalAvailable": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991,
                "description": "Potential matches this node's screen found before the per-node cap was applied."
              },
              "totalAvailableBasis": {
                "type": "string",
                "enum": [
                  "exact",
                  "lower_bound"
                ],
                "description": "How to read totalAvailable: exact = the complete strict match set for this node; lower_bound = a bounded scan produced it, so more may exist."
              },
              "hasMore": {
                "type": "boolean",
                "description": "True when this node's potential matches were capped — screen its legal name with sanctions_screen_name to page through the rest."
              }
            },
            "required": [
              "totalAvailable",
              "totalAvailableBasis",
              "hasMore"
            ],
            "additionalProperties": false
          },
          "sanctionsHits": {
            "description": "Per-node screening results, present only when screenNodes is true.",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "source": {
                  "type": "string",
                  "enum": [
                    "ofac_sdn",
                    "ofac_consolidated",
                    "eu",
                    "uk",
                    "un"
                  ],
                  "description": "Watchlist the candidate is on."
                },
                "sourceLabel": {
                  "type": "string",
                  "description": "Human-readable source list name."
                },
                "sourceEntryId": {
                  "type": "string",
                  "description": "Source entry ID — pass to sanctions_get_designation."
                },
                "primaryName": {
                  "type": "string",
                  "description": "Primary published name of the designation."
                },
                "matchedName": {
                  "type": "string",
                  "description": "The name/alias that matched this node."
                },
                "matchType": {
                  "type": "string",
                  "enum": [
                    "exact",
                    "strong",
                    "approximate"
                  ],
                  "description": "Match classification."
                },
                "score": {
                  "description": "Raw Jaro-Winkler similarity (0–1) for approximate hits only.",
                  "type": "number"
                }
              },
              "required": [
                "source",
                "sourceLabel",
                "sourceEntryId",
                "primaryName",
                "matchedName",
                "matchType"
              ],
              "additionalProperties": false,
              "description": "A potential watchlist match on this node — verify, do not assume."
            }
          }
        },
        "required": [
          "lei",
          "legalName",
          "depth",
          "role"
        ],
        "additionalProperties": false,
        "description": "One entity in the ownership graph."
      },
      "description": "All entities reached in the traversal, including the root."
    },
    "edges": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "childLei": {
            "type": "string",
            "description": "LEI of the owned (child) entity."
          },
          "parentLei": {
            "type": "string",
            "description": "LEI of the owning (parent) entity."
          },
          "relationshipType": {
            "type": "string",
            "description": "GLEIF relationship type (e.g. IS_DIRECTLY_CONSOLIDATED_BY)."
          },
          "relationshipStatus": {
            "description": "Relationship status, when published.",
            "type": "string"
          }
        },
        "required": [
          "childLei",
          "parentLei",
          "relationshipType"
        ],
        "additionalProperties": false,
        "description": "One directed ownership edge (child is consolidated by parent)."
      },
      "description": "Directed ownership edges between the nodes."
    },
    "complete": {
      "type": "boolean",
      "description": "True when the loaded Level 2 relationships within the requested depth are all shown (nothing was cut off by depth) AND every node resolved to a GLEIF Level 1 record. It does not say every parent is known — most entities publish no parent relationship; read each node's parentStatus for what GLEIF publishes instead. False means the graph below is a partial view — read truncated and missingEntityLeis for which."
    },
    "truncated": {
      "type": "boolean",
      "description": "True when further ownership relationships exist beyond the requested depth — re-run with a higher depth to see them. False means the traversal reached the edge of the loaded relationship corpus."
    },
    "reportingExceptionsLoaded": {
      "type": "boolean",
      "description": "Whether GLEIF reporting exceptions are loaded in the mirror. When false, a node's parent level with no published relationship reads unknown rather than exception or none."
    },
    "missingEntityLeis": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "LEIs published in the relationship corpus but absent from the GLEIF Level 1 entity mirror. Their nodes carry the LEI in place of a legal name and no jurisdiction/status — never read that LEI as a legal name, and note any per-node screen for them ran against the LEI string."
    },
    "screeningStatus": {
      "type": "string",
      "enum": [
        "screened",
        "not_requested",
        "not_ready"
      ],
      "description": "Whether the per-node cross-reference ran: screened = every node was screened; not_requested = screenNodes was false; not_ready = screening was requested but the sanctions mirror has never synced, so NO node was screened and the absence of hits says nothing about any node."
    },
    "screenedNodeCount": {
      "type": "number",
      "description": "How many nodes were screened (0 when screenNodes is false)."
    },
    "flaggedNodeCount": {
      "type": "number",
      "description": "How many screened nodes had at least one potential watchlist match."
    },
    "caveat": {
      "type": "string",
      "description": "Decision-support caveat — node screening is an aid, not a determination."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `lei_not_found`: No GLEIF entity exists for the root LEI in the mirror. `mirror_not_ready`: The GLEIF (LEI) mirror has never completed an initial sync. Other values are possible when a failure originates below the handler.",
              "examples": [
                "lei_not_found",
                "mirror_not_ready"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "rootLei",
        "nodes",
        "edges",
        "complete",
        "truncated",
        "reportingExceptionsLoaded",
        "missingEntityLeis",
        "screeningStatus",
        "screenedNodeCount",
        "flaggedNodeCount",
        "caveat"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}