Get started

Agent Toolkit: tool reference

Ten tools across two trust models. Six are Nexiel Verify/Age tools, all either initiate-or-read-only (nothing here can resolve or clear a POSSIBLE_MATCH result, and no tool ever returns raw PII), authorized by whatever bearer token your MCP client was configured with. See the quickstart for how that token is scoped and forwarded. Four are Nexiel Invoice/ViDA tools: pure compute, no bearer token, no persistence. See the compute badge below and the quickstart's "Nexiel Invoice / ViDA tools" section for exactly what that does and does not cover.

create_verification_session initiates

Initiates a Nexiel Verify EUDI wallet session for a full AML/identity check (checkType "aml-identity"). The wallet discloses given_name/family_name/birthdate/nationalities, and the holder is screened against sanctions/PEP data via the shared matching engine once the wallet responds.

Parameters

  • clientId (string), required. Opaque correlation id for the verification subject, never a name, email, or other directly-identifying value.
  • idempotencyKey (string (optional)) Client-supplied idempotency key. Generated automatically when omitted, never skipped.

Response

sessionId, templateVersion, authorizationRequest (the DCQL query object), authorizationRequestUri (for a wallet to resolve), expiresAt.

  • Only INITIATES the session: the AML result does not exist until the wallet responds. Read it back with get_verification_session or get_verification_session_result.
  • A POSSIBLE_MATCH outcome can NEVER be resolved or cleared through this tool, or anywhere else in this toolkit: EU AI Act human-in-the-loop always applies.

create_age_verification_session initiates

Initiates a Nexiel Age / Nexiel Verify EUDI wallet session (checkType "age-verification") offering the wallet two alternative ways to answer, via DCQL credential_sets: the EU's official Age Verification (AV) attestation, if the wallet holds one -- a native age_over_18 boolean, no birthdate ever disclosed at all -- or the PID's birthdate claim as a fallback where it doesn't, used solely to compute the same boolean server-side and discarded immediately. A conformant wallet answers exactly one: selective disclosure by construction, not by convention, either way.

Parameters

  • clientId (string), required. Opaque correlation id for the verification subject.
  • idempotencyKey (string (optional)) Same semantics as create_verification_session.

Response

sessionId, templateVersion, authorizationRequest, authorizationRequestUri, expiresAt.

  • No name or nationality is ever requested by this check type, on either path. When the PID fallback is used, the wallet discloses a birthdate, but it is used only to compute the age_over_18 boolean and is never stored, logged, or returned by any tool.

get_verification_session read-only

Reads back a session's full status and, once completed, its decision.

Parameters

  • sessionId (string (uuid)), required. The sessionId returned by either create_* tool.

Response

sessionId, clientId, checkType, templateVersion, status ("pending" | "completed" | "failed" | "expired"), createdAt, expiresAt, and decision (null until completed): method, booleanProofs, amlResult, pepFlag, sanctionedFlag, listsChecked, humanReviewRequired, frozenDecisionArtifact, evidencePackCiphertext, decidedAt.

  • Never returns raw PII: only the same non-PII fields verify-api itself persists (session id, client id, timestamp, method, boolean proofs, aml result, pep/sanctioned booleans, lists checked).
  • frozenDecisionArtifact (engineVersion, gatesHash, ensembleWeightsHash, listSnapshotIds) is PINNED at decision time, never recomputed from whatever config is loaded when you call this tool.
  • evidencePackCiphertext is always null through this tool. An aml-identity session may separately carry a one-time-delivery encrypted AMLR evidence pack, but this tool reads the session in peek mode and can never trigger or consume that delivery. Actual delivery only ever happens via a real client calling GET /v1/verify/sessions/:sessionId directly.

get_verification_session_result read-only

A narrower projection of get_verification_session: just the decision, for a caller that only cares about the outcome, not session metadata. It always reads the same session data, never a separate or stale copy.

Parameters

  • sessionId (string (uuid)), required. The sessionId to read back.

Response

sessionId, status, and decision (or, if not yet completed, decision: null plus an explanatory note naming the current status).

  • Same non-PII guarantee and human-review guarantee as get_verification_session.

list_verification_sessions read-only

Lists verification sessions scoped to the calling API key's own client identity, most-recently-created first.

Parameters

  • clientId (string (optional)) Only consulted against an unauthenticated sandbox-mode verify-api deployment, ignored for any real, authenticated caller (your own key's identity always wins).
  • limit (integer 1-100 (optional)) Defaults to 20.

Response

sessions: an array of the same shape get_verification_session returns.

  • A production caller can only ever see sessions belonging to their own API key's identity, never another client's.

get_decision_artifact read-only

Returns ONLY the frozen decision artifact for a completed aml-identity session: the exact, re-derivable answer to "what logic ran for this case."

Parameters

  • sessionId (string (uuid)), required. The sessionId to read the artifact for.

Response

sessionId, frozenDecisionArtifact: { engineVersion, gatesHash, ensembleWeightsHash, listSnapshotIds }, or null with an explanatory note if the session is not yet completed, or is an age-verification check (which never runs an AML/PEP screen at all).

  • gatesHash is the SHA-256 of the entire gates.json config in force AT DECISION TIME, not whatever config is loaded now.
  • listSnapshotIds names the exact etl_runs snapshots that could have contributed a candidate to this specific decision.

validate_en16931_invoice compute

Runs @nexiel/einvoice's real 32-rule EN 16931 business-rule validator (the same engine that gates real invoice issuance in the Nexiel Invoice dashboard) against a fully-formed invoice you supply.

Parameters

  • invoice (EN16931Invoice object), required. The full semantic invoice model (@nexiel/einvoice's own EN16931Invoice shape): seller/buyer, lines, vatBreakdown, and totals. This tool does NOT compute totals or VAT breakdown for you. Supply an already-balanced invoice exactly as the real rules (BR-CO-10..17 etc.) expect to check it.

Response

valid (boolean) and ruleResults: the full list of every rule checked, including passing ones, each with a ruleId/passed/message.

  • No bearer token is read or required. This tool touches no stored customer data, only the invoice you pass in this same call.
  • Nothing is persisted or issued. This only reports whether the invoice you supplied is valid.

generate_en16931_invoice_document compute

Validates a fully-formed invoice (same real rule engine as validate_en16931_invoice) and, if valid, serializes it to a real Peppol BIS Billing 3.0 UBL 2.1 or CII XML document via @nexiel/einvoice's actual serializers.

Parameters

  • invoice (EN16931Invoice object), required. Same shape as validate_en16931_invoice.
  • syntax ("UBL" | "CII" (optional)) Defaults to "UBL".

Response

valid (boolean) plus either xml (the generated document text, syntax "UBL"|"CII") when valid, or ruleResults (only the failing rules) plus an explanatory note when invalid.

  • An invalid invoice is never serialized. That mirrors the real dashboard issuing pipeline's own gate.
  • Nothing is persisted anywhere by this tool. It only returns the generated XML text to you.

submit_invoice_to_sandbox_peppol compute

Exercises @nexiel/peppol-transport's real, vendor-agnostic transport interface: always against the SANDBOX provider (send, then immediately check delivery status, in the same call).

Parameters

  • invoice (MinimalInvoice object), required. peppol-transport's own narrower invoice shape (seller/buyer/lines/totals): a different, smaller shape than validate_en16931_invoice's EN16931Invoice, by design (see the quickstart's note on why these two shapes are kept separate).
  • recipient (array of { scheme, id }), required. At least one Peppol participant identifier, e.g. { scheme: "IE:VAT", id: "IE1234567T" }.
  • documentType ("invoice" | "credit_note" (optional)) Defaults to "invoice".
  • legalEntityId (string), required. Opaque sandbox sender identity. No real vendor account concept exists behind this.
  • idempotencyKey (string), required. Required (every mutating action needs one). The sandbox provider dedupes on it.

Response

submission (the send() result) and delivery (the immediate getDeliveryStatus() result), plus an explanatory note.

  • network is always "sandbox" on both submission and delivery. That is enforced in code, not merely documented: the transport factory throws rather than ever unlocking a real vendor, so no real Peppol/AS2/vendor transmission is possible through this tool.
  • Ephemeral and NOT persisted: a fresh, isolated in-memory provider backs each call, so this submission cannot be looked up again later by this tool, any other tool, or the Nexiel Invoice dashboard.

check_peppol_participant_can_receive compute

Exercises @nexiel/peppol-transport's real checkParticipantCanReceive() discovery call: always against the sandbox provider.

Parameters

  • identifier ({ scheme, id }), required. The Peppol participant identifier to check.

Response

identifier, canReceive (boolean), providerName (always "sandbox-mock").

  • The sandbox's real, deterministic rule: any identifier whose id ends in "-unreachable" is reported unable to receive. Every other identifier is reported reachable.
  • Not a real network discovery lookup against the live Peppol network.

What this toolkit will never do