Screen a person or organization name against the Sugra sanctions corpus.
Returns a SCREENING SIGNAL, not a compliance determination. Sugra is a
technology provider, not a sanctions authority or consumer reporting agency.
PEP and adverse-media coverage is supplementary and non-comprehensive - a
`clear` result is not proof of absence, and a `hit` is a candidate match to
review, not a finding.
Output is COMPACT to protect the agent context budget:
`{status, matches:[{name, score, list, type}], disclaimer}`. The verdict
`status` is one of `clear`, `review`, or `hit`. The heavy raw fields
(match rationale, source ids, publish dates) are dropped; use the Sugra API
directly when the full screening envelope is needed.
Args:
name: The person or organization name to screen (required).
country: Optional ISO 3166-1 alpha-2 country to narrow the match.
dob: Optional date of birth (YYYY-MM-DD) for a person.
nationality: Optional nationality to narrow the match.
Resolve an entity by identifier and return its composed KYB envelope.
`anchor` is `lei` (Legal Entity Identifier, resolved via the GLEIF registry)
or `vat` (EU VAT number, validated via the EU VIES service). The result
weaves identity, a sanctions screening signal, and - on request - ownership
and adverse-media slices.
The screening verdict is a SCREENING SIGNAL, not a compliance determination,
and any PEP / adverse-media content is supplementary and non-comprehensive.
The `disclaimer` field carries this and is always present.
Output is COMPACT by default to protect the agent context budget:
`{entity:{name, anchor, value, status, country}, screening:{status,
top_matches:[...3], hit_count}, ids:{...}, disclaimer}`. Pass `include` to
opt INTO fuller per-slice detail, e.g.
`include=["ownership","adverse_media"]` adds those slices in full form.
On a bad anchor or an API error this returns a clean `{error, detail}` dict
rather than raising, so the agent can branch on `result.get("error")`.
Args:
anchor: Identifier type, one of `lei` or `vat`.
value: The identifier value (the 20-char LEI code or the VAT number).
include: Optional list of fuller slices to add, e.g.
`["ownership", "adverse_media"]`. Omit for the compact default.
Search the bundled Sugra endpoint catalog by natural-language query.
Use this to pick an operation_id. It does not fetch data. Typical loop:
1. search_endpoints(query) -> ranked hits with required_parameters
2. describe_endpoint(operation_id) -> params, request_body_schema, agent_hints
3. call_endpoint(operation_id, params=..., body=...) or fetch_data(query, params=...)
Filter with toolset or source only after list_toolsets / list_sources;
a misspelled filter is an error, not a silent empty result.
Examples:
- search_endpoints("US CPI inflation")
- search_endpoints("AAPL price", toolset="markets")
- search_endpoints("container ship AIS", toolset="network")
Describe one Sugra API endpoint by operation_id.
Includes agent_hints (duration_class fast/slow/heavy, max_concurrency,
bulk billing) so you can budget timeouts and parallelism before calling.
POST endpoints with a JSON body also carry request_body_schema (the
resolved JSON schema) - construct the `body` argument from it instead
of guessing key names. Call this after search_endpoints and before
call_endpoint when you need the exact parameter names and examples.
Call a Sugra API endpoint by operation_id from the bundled catalog.
Plan calls with describe_endpoint's agent_hints: duration_class "fast"
usually responds in under ~2s, "slow" usually 1-5s and occasionally 15s+
on a cold upstream, "heavy" can exceed the gateway timeout - keep parallel
calls within max_concurrency and prefer small batches. Bulk endpoints bill
1 request credit per body item. Failures return structured errors {error,
reason, status_code, elapsed_ms, retry_hint}; after "upstream_timeout" a
single retry often succeeds because the aborted attempt warms upstream
caches.
List catalog groups with endpoint counts and short descriptions.
Use the group names as the toolset filter on search_endpoints. This
does not call the Sugra API; it reads the bundled catalog.
One-step fetch: find the best Sugra endpoint for the query and call it.
Combines search_endpoints + call_endpoint into a single round trip. Use
this when you want data without manually picking an operation_id. The
full search_endpoints + describe_endpoint + call_endpoint dance is still
available when you need explicit control, but for most natural-language
queries this tool is enough.
Behavior:
1. Search the bundled catalog for the query. Top match wins.
2. If the matched endpoint has required parameters and they are all
provided in `params`, call it and return the response.
3. If required parameters are missing, return the candidate endpoints
and the missing-params list so the LLM can retry with the correct
`params` dict on the next call.
Examples:
- `fetch_data("US CPI inflation", params={"series_id": "CPIAUCSL"})`
→ calls /api/v1/fred/series/CPIAUCSL, returns observations.
- `fetch_data("Bitcoin price", params={"coin_id": "bitcoin"})`
→ calls /api/v1/crypto/bitcoin/price.
- `fetch_data("Latest financial news")`
→ news_latest has no required params, returns latest news directly.
List source families in the bundled catalog with endpoint counts.
Use the family names as the source filter on search_endpoints. This
does not call the Sugra API.