Skip to main content
Glama

sanctions-screening-mcp-server

sanctions-screening-mcp-server: screen name

sanctions_screen_name
Read-onlyIdempotent

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; an OFAC party both OFAC lists publish under one entry ID is one hit, its sources naming both lists. Strict mode (default) matches exact-normalized then all-tokens-present, then runs a fuzzy pass over each selected list strict finds nothing on: a full pass when strict finds nothing on any list, otherwise one that adds only candidates covering every word of the name other than legal forms, articles and other function words, and the jurisdiction codes uk, usa, uae, and rf, ranked after the strict hits. Fuzzy mode runs the fuzzy pass over every selected list. It 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; fuzzySources names the lists it searched. 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."

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
nameYesThe 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.
limitNoMaximum number of potential matches to return in one page.
offsetNoZero-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.
sourcesNoRestrict to specific source lists. Omit to screen all loaded lists.
minScoreNoScore floor for approximate hits (0–1), applied uniformly to every fuzzy candidate regardless of how it was matched (Jaro-Winkler, token, or phonetic); a query token counts toward queryTokenCoverage only when its match clears it too. It governs every fuzzy pass: fuzzy mode, and in strict mode the pass over the lists strict found nothing on, so raising it can remove approximate hits from a strict screen as well. Exact and strong hits are unaffected. Defaults to the server's configured floor.
matchModeNostrict (default): exact-normalized then all-tokens-present, then a fuzzy pass over each selected list strict finds nothing on — a full pass when strict finds nothing on any list, otherwise adding only candidates that cover every word of the name other than legal forms, articles and other function words, and the jurisdiction codes uk, usa, uae, and rf. fuzzy: a scored Jaro-Winkler + phonetic pass over every selected list.strict
entityTypeNoRestrict to one entity class, or "any" (default) to screen across all.any

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
hitsNoPotential matches, ranked by match type, then score, then how much of the query each candidate explains. Candidates tied on all three are ordered by source list, then entry ID — not by relevance.
errorNoPresent when the call failed. Absent on success.
caveatNoDecision-support caveat — this is a screening aid, not a compliance determination.
noticeNoGuidance when no candidate matched — how to broaden, and what an empty result does NOT mean — when the requested offset sits past the end of the result set, or when the fuzzy pass reached its candidate bound and a more distinctive word would narrow it.
hasMoreNoTrue when the result set holds matches beyond this page — re-call with nextOffset. It describes pages only: false on the last page, whatever totalAvailableBasis says.
nextOffsetNoThe offset to request next. Present only when hasMore is true.
totalCountNoNumber of potential matches returned in this page.
fuzzySourcesNoThe selected lists the fuzzy pass searched, in list order; absent when no fuzzy pass ran. Beside strict hits these are the lists strict found nothing on, and only their candidates covering every word of the name other than legal forms, articles and other function words, and the jurisdiction codes uk, usa, uae, and rf were added.
matchModeUsedNofuzzy when every selected list was fuzzy-searched (fuzzy mode, or a strict screen that found nothing on any list); strict otherwise, including a strict screen whose strict-empty lists were completed by a fuzzy pass.
totalAvailableNoPotential matches in the result set across all pages, before limit and offset were applied — every one is reachable by paging. An OFAC party both OFAC lists publish counts once.
normalizedQueryNoThe name as the server folded it for matching.
totalAvailableBasisNoHow to read totalAvailable: exact = the complete strict match set, strict having found a match on every selected list; lower_bound = a fuzzy pass ran (fuzzySources is present), which scores only the candidates blocking pooled, so more matches may exist beyond the result set.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed13 schema fields changed
    • changedInput schema / properties / matchMode / description
      Previous value: -"strict (default): exact-normalized then all-tokens-present. fuzzy: also scored Jaro-Winkler + phonetic. Strict auto-falls-back to fuzzy when it finds nothing."New value: +"strict (default): exact-normalized then all-tokens-present, then a fuzzy pass over each selected list strict finds nothing on — a full pass when strict finds nothing on any list, otherwise adding only candidates that cover every word of the name other than legal forms, articles and other function words, and the jurisdiction codes uk, usa, uae, and rf. fuzzy: a scored Jaro-Winkler + phonetic pass over every selected list."
    • changedInput schema / properties / minScore / description
      Previous value: -"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."New value: +"Score floor for approximate hits (0–1), applied uniformly to every fuzzy candidate regardless of how it was matched (Jaro-Winkler, token, or phonetic); a query token counts toward queryTokenCoverage only when its match clears it too. It governs every fuzzy pass: fuzzy mode, and in strict mode the pass over the lists strict found nothing on, so raising it can remove approximate hits from a strict screen as well. Exact and strong hits are unaffected. Defaults to the server's configured floor."
    • addedOutput schema / properties / fuzzySources
      Added value: +{
      +  "description": "The selected lists the fuzzy pass searched, in list order; absent when no fuzzy pass ran. Beside strict hits these are the lists strict found nothing on, and only their candidates covering every word of the name other than legal forms, articles and other function words, and the jurisdiction codes uk, usa, uae, and rf were added.",
      +  "items": {
      +    "enum": [
      +      "ofac_sdn",
      +      "ofac_consolidated",
      +      "eu",
      +      "uk",
      +      "un"
      +    ],
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • changedOutput schema / properties / hasMore / description
      Previous value: -"True when potential matches remain beyond this page — re-call with nextOffset."New value: +"True when the result set holds matches beyond this page — re-call with nextOffset. It describes pages only: false on the last page, whatever totalAvailableBasis says."
    • changedOutput schema / properties / hits / description
      Previous value: -"Potential matches, ranked by match type, then score, then how much of the query each candidate explains."New value: +"Potential matches, ranked by match type, then score, then how much of the query each candidate explains. Candidates tied on all three are ordered by source list, then entry ID — not by relevance."
    • changedOutput schema / properties / hits / items / properties / designationDate / description
      Previous value: -"The source's own designation date as YYYY-MM-DD; absent when unpublished."New value: +"The source's own designation date as YYYY-MM-DD; absent when unpublished. For an OFAC party both OFAC lists publish, the date of the source record: each OFAC file dates the party from its own lists, so the two often differ, and sanctions_get_designation under the other list returns that record's date."
    • changedOutput schema / properties / hits / items / properties / source / description
      Previous value: -"Which watchlist this candidate is on — its provenance."New value: +"The watchlist whose record this hit's fields come from — its provenance. For an OFAC party both OFAC lists publish, ofac_sdn unless the Consolidated record matched alone or better; sources names every list."
    • addedOutput schema / properties / hits / items / properties / sources
      Added value: +{
      +  "description": "Every screened list this candidate is on, in list order: one list, or ofac_sdn and ofac_consolidated together for an OFAC party both OFAC lists publish under one entry ID — one hit, not two. Read this, not source, for every list; the entry ID resolves in sanctions_get_designation under each.",
      +  "items": {
      +    "enum": [
      +      "ofac_sdn",
      +      "ofac_consolidated",
      +      "eu",
      +      "uk",
      +      "un"
      +    ],
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • changedOutput schema / properties / hits / items / required
      Previous value: -[
      -  "source",
      -  "sourceLabel",
      -  "sourceEntryId",
      -  "entityType",
      -  "primaryName",
      -  "matchedName",
      -  "matchedNameType",
      -  "matchType"
      -]New value: +[
      +  "source",
      +  "sourceLabel",
      +  "sourceEntryId",
      +  "sources",
      +  "entityType",
      +  "primaryName",
      +  "matchedName",
      +  "matchedNameType",
      +  "matchType"
      +]
    • changedOutput schema / properties / matchModeUsed / description
      Previous value: -"The match mode actually applied (strict may auto-upgrade to fuzzy on empty)."New value: +"fuzzy when every selected list was fuzzy-searched (fuzzy mode, or a strict screen that found nothing on any list); strict otherwise, including a strict screen whose strict-empty lists were completed by a fuzzy pass."
    • changedOutput schema / properties / notice / description
      Previous value: -"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."New value: +"Guidance when no candidate matched — how to broaden, and what an empty result does NOT mean — when the requested offset sits past the end of the result set, or when the fuzzy pass reached its candidate bound and a more distinctive word would narrow it."
    • changedOutput schema / properties / totalAvailable / description
      Previous value: -"Potential matches available across all pages, before limit and offset were applied."New value: +"Potential matches in the result set across all pages, before limit and offset were applied — every one is reachable by paging. An OFAC party both OFAC lists publish counts once."
    • changedOutput schema / properties / totalAvailableBasis / description
      Previous value: -"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."New value: +"How to read totalAvailable: exact = the complete strict match set, strict having found a match on every selected list; lower_bound = a fuzzy pass ran (fuzzySources is present), which scores only the candidates blocking pooled, so more matches may exist beyond the result set."
  2. Changed2 schema fields changed
    • changedOutput schema / properties / hits / items / properties / designationDate / description
      Previous value: -"Designation date as published, when available."New value: +"The source's own designation date as YYYY-MM-DD; absent when unpublished."
    • addedOutput schema / properties / hits / items / properties / referenceNumber
      Added value: +{
      +  "description": "The list's published reference number (UN, EU, UK OFSI Group ID); absent when the list publishes none for the entry.",
      +  "type": "string"
      +}
  3. Changed3 schema fields changed
    • changedInput schema / properties / name / description
      Previous value: -"The name to screen (person, organization, vessel, or aircraft)."New value: +"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."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `mirror_not_ready`: The sanctions mirror has never completed an initial sync. Other values are possible when a failure originates below the handler."New value: +"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."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "mirror_not_ready"
      -]New value: +[
      +  "name_not_searchable",
      +  "name_too_long",
      +  "mirror_not_ready"
      +]
  4. Changed6 schema fields changed
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / additionalProperties
      Added value: +false
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedOutput schema / anyOf
      Added value: +[
      +  {
      +    "not": {
      +      "required": [
      +        "error"
      +      ]
      +    },
      +    "required": [
      +      "hits",
      +      "caveat",
      +      "normalizedQuery",
      +      "matchModeUsed",
      +      "totalCount",
      +      "totalAvailable",
      +      "totalAvailableBasis",
      +      "hasMore"
      +    ]
      +  },
      +  {
      +    "required": [
      +      "error"
      +    ]
      +  }
      +]
    • addedOutput schema / properties / error
      Added value: +{
      +  "additionalProperties": {},
      +  "description": "Present when the call failed. Absent on success.",
      +  "properties": {
      +    "code": {
      +      "description": "JSON-RPC error code for this failure.",
      +      "maximum": 9007199254740991,
      +      "minimum": -9007199254740991,
      +      "type": "integer"
      +    },
      +    "data": {
      +      "additionalProperties": {},
      +      "properties": {
      +        "reason": {
      +          "description": "Machine-readable failure mode. Declared by this tool: `mirror_not_ready`: The sanctions mirror has never completed an initial sync. Other values are possible when a failure originates below the handler.",
      +          "examples": [
      +            "mirror_not_ready"
      +          ],
      +          "type": "string"
      +        },
      +        "recovery": {
      +          "additionalProperties": {},
      +          "description": "Actionable next step for the caller.",
      +          "properties": {
      +            "hint": {
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "hint"
      +          ],
      +          "type": "object"
      +        },
      +        "retryable": {
      +          "description": "Whether retrying may succeed.",
      +          "type": "boolean"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "message": {
      +      "description": "Human-readable description of what went wrong.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "code",
      +    "message"
      +  ],
      +  "type": "object"
      +}
    • removedOutput schema / required
      Removed value: -[
      -  "hits",
      -  "caveat",
      -  "normalizedQuery",
      -  "matchModeUsed",
      -  "totalCount",
      -  "totalAvailable",
      -  "totalAvailableBasis",
      -  "hasMore"
      -]
  5. Changed11 schema fields changed
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum number of potential matches to return."New value: +"Maximum number of potential matches to return in one page."
    • addedInput schema / properties / offset
      Added value: +{
      +  "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.",
      +  "maximum": 9007199254740991,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • addedOutput schema / properties / hasMore
      Added value: +{
      +  "description": "True when potential matches remain beyond this page — re-call with nextOffset.",
      +  "type": "boolean"
      +}
    • changedOutput schema / properties / hits / description
      Previous value: -"Scored potential matches, highest-confidence first."New value: +"Potential matches, ranked by match type, then score, then how much of the query each candidate explains."
    • addedOutput schema / properties / hits / items / properties / queryTokenCoverage
      Added value: +{
      +  "additionalProperties": false,
      +  "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.",
      +  "properties": {
      +    "covered": {
      +      "description": "Query tokens individually matched by one of this candidate's tokens at the applied score floor.",
      +      "maximum": 9007199254740991,
      +      "minimum": -9007199254740991,
      +      "type": "integer"
      +    },
      +    "total": {
      +      "description": "Total tokens in the normalized query.",
      +      "maximum": 9007199254740991,
      +      "minimum": -9007199254740991,
      +      "type": "integer"
      +    }
      +  },
      +  "required": [
      +    "covered",
      +    "total"
      +  ],
      +  "type": "object"
      +}
    • addedOutput schema / properties / nextOffset
      Added value: +{
      +  "description": "The offset to request next. Present only when hasMore is true.",
      +  "type": "number"
      +}
    • changedOutput schema / properties / notice / description
      Previous value: -"Guidance when no candidate matched — how to broaden, and what an empty result does NOT mean."New value: +"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."
    • addedOutput schema / properties / totalAvailable
      Added value: +{
      +  "description": "Potential matches available across all pages, before limit and offset were applied.",
      +  "type": "number"
      +}
    • addedOutput schema / properties / totalAvailableBasis
      Added value: +{
      +  "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.",
      +  "enum": [
      +    "exact",
      +    "lower_bound"
      +  ],
      +  "type": "string"
      +}
    • changedOutput schema / properties / totalCount / description
      Previous value: -"Number of potential matches returned."New value: +"Number of potential matches returned in this page."
    • changedOutput schema / required
      Previous value: -[
      -  "hits",
      -  "caveat",
      -  "normalizedQuery",
      -  "matchModeUsed",
      -  "totalCount"
      -]New value: +[
      +  "hits",
      +  "caveat",
      +  "normalizedQuery",
      +  "matchModeUsed",
      +  "totalCount",
      +  "totalAvailable",
      +  "totalAvailableBasis",
      +  "hasMore"
      +]
  6. Changed1 schema field changed
    • changedInput schema / properties / minScore / description
      Previous value: -"Jaro-Winkler similarity floor for fuzzy hits (0–1). Applies to fuzzy mode only; defaults to the server's configured floor."New value: +"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."
  7. First observed

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish read-only, idempotent, closed-world behavior, and the description adds substantial context beyond them: deduplication of OFAC entries by entry ID, how minScore propagates into strict-mode fuzzy passes, the nextOffset/totalAvailable/hasMore paging contract, and the explicit caveat that a hit is not a determination and an empty result is not a clearance.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is front-loaded in the first clause, which is good, but the remainder is a single very dense block whose matching-semantics sentences are largely duplicated verbatim in the matchMode and minScore schema descriptions. It is information-rich but not economically written.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex screening tool with an output schema and rich annotations, the description covers the full operational picture: scoring and tie-breaking, list coverage, mode behavior, pagination, and the compliance-review framing. Nothing an agent needs to call it correctly or interpret results is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains how minScore interacts with matchMode and queryTokenCoverage, how strict vs fuzzy changes what sources are searched, and how offset/nextOffset paging behaves past the end. The matchMode and minScore prose largely restates the schema wording, capping this at 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Screen a name ... against all loaded sanctions watchlists at once'), enumerates the entity classes and the source lists covered, and its name-based framing distinguishes it from the identifier-based sibling sanctions_screen_identifier. An agent can select it without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear operational context: strict is the default, fuzzy is opt-in, and it explains the cascade behavior when strict finds nothing. It does not, however, explicitly route between this tool and the sibling sanctions_screen_identifier, so the choice of 'name vs identifier' is left to inference from the tool name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.