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.