Reconcile expected payments against observed bank-statement entries.

Purpose: Matches expected payment instructions (e.g. from pain.001) against observed bank transactions (e.g. from camt.053) and produces an explainable reconciliation report covering exact matches, short/over adjustments, split settlements (one-to-many), batch credits (many-to-one), and unmatched residuals.

When to use:

• When performing multi-transaction cash reconciliation between ledgers and statements.

• When transparent per-match confidence scores and reason breakdowns are required for audit.

When NOT to use:

• Do NOT use for raw, unparsed XML files; normalize input documents first using normalize_pain001 or normalize_camt053.

• Do NOT use for single-pair tuning analysis; use explain_match instead.

• Do NOT use for unconstrained combinatorial invoice subsets; use reconcile_many_to_many.

Behavioral transparency: Pure, deterministic, side-effect-free, read-only calculation without network or disk access.

Explain the match score between one expected and one observed record.

Purpose: Scores a single transaction pair across reference, amount, date, and name signals, returning individual signal weights and an explanation even for pairs below threshold.

When to use:

• When tuning scoring weights, tolerances, or debugging match decisions.

• When explaining match confidence for human review or exception handling.

When NOT to use:

• Do NOT use for entire batches; use reconcile instead.

• Do NOT use for cross-currency conversions without a known FX rate; use match_amounts_with_fx_drift.

Behavioral transparency: Pure, deterministic, side-effect-free, read-only calculation without external dependencies.

Convert parsed pain.001 payment instructions into canonical expected records.

Purpose: Adapts parsed ISO 20022 pain.001 credit transfer documents or transaction lists into canonical expected records ready for the reconcile engine.

When to use:

• When ingesting parsed pain.001 files before calling reconcile.

• When mapping diverse payment field structures into uniform id, amount, and reference fields.

When NOT to use:

• Do NOT use for bank statement entries (camt.053); use normalize_camt053 instead.

• Do NOT pass raw unparsed XML text; parse or deserialize to a dictionary or list first.

Behavioral transparency: Pure, deterministic, read-only data normalization.

Convert parsed camt.053 statement entries into canonical observed records.

Purpose: Adapts parsed ISO 20022 camt.053 bank statement documents or entry lists into canonical observed records ready for the reconcile engine.

When to use:

• When ingesting parsed bank statements before calling reconcile.

• When transforming bank booking entries into uniform id, amount, date, and counterparty fields.

When NOT to use:

• Do NOT use for payment initiation orders (pain.001); use normalize_pain001 instead.

• Do NOT pass raw unparsed XML text; parse or deserialize first.

Behavioral transparency: Pure, deterministic, read-only data normalization.

List built-in sandbox reconciliation scenarios and magic references.

Purpose: Returns the catalog of deterministic test-mode scenarios and synthetic magic references to demonstrate reconciliation outcomes without production data.

When to use:

• When discovering available test scenarios (e.g. clean_match, month_end, fx_drift).

• When testing agent decision-making workflows with zero setup.

When NOT to use:

• Do NOT use for production reconciliation batches.

Behavioral transparency: Static catalogue retrieval; read-only and instantaneous.

Load expected and observed record inputs for a named sandbox scenario.

Purpose: Retrieves the test-mode expected and observed fixture records for a named scenario so they can be inspected, customized, or passed to reconcile.

When to use:

• When reviewing fixture data prior to executing reconciliation runs.

• When creating custom variations of standard reconciliation scenarios.

When NOT to use:

• Do NOT use if you want to run and reconcile the scenario in one step; use run_sandbox_scenario.

• Do NOT use with non-existent scenario names.

Behavioral transparency: Deterministic dictionary lookup; read-only with no side effects.

Load a named sandbox scenario and immediately return its reconciliation report.

Purpose: One-call execution that loads built-in fixture records and executes the reconciliation pipeline, returning a complete explainable match report.

When to use:

• When performing quick verification, smoke tests, or initial agent demonstrations.

• When verifying tolerance tuning against standard test cases.

When NOT to use:

• Do NOT use with live production data.

• Do NOT use when custom expected or observed records must be supplied; use reconcile instead.

Behavioral transparency: Deterministic, in-memory execution; read-only and idempotent.

Score two counterparty names using Jaro-Winkler string similarity.

Purpose: Computes similarity in [0, 1] between two company or individual names, tolerating typographical variations and legal suffix abbreviations (e.g. 'Corp' vs 'Corporation Inc').

When to use:

• When verifying whether two counterparty or entity names represent the same party.

• When evaluating name similarity thresholds for automated matching rules.

When NOT to use:

• Do NOT use for full multi-signal transaction matching; use reconcile or explain_match.

• Do NOT use with non-string inputs.

Behavioral transparency: Pure, deterministic string calculation; read-only and idempotent.

Compare two amounts in different currencies within an FX drift tolerance.

Purpose: Converts currency amounts using a provided exchange rate and verifies if the percentage difference falls within an acceptable tolerance window using exact decimal arithmetic.

When to use:

• When reconciling cross-currency payments with conversion timing or rate variance.

• When evaluating FX tolerance bounds on cross-border transactions.

When NOT to use:

• Do NOT use for same-currency comparisons where standard tolerance applies; use reconcile.

• Do NOT use with non-positive FX rates.

Behavioral transparency: Pure mathematical calculation; read-only and idempotent.

Match statement deposits to disjoint subsets of invoices via subset-sum ILP.

Purpose: Solves bounded subset-sum as an integer linear program (ILP) to pair statement deposits against matching combinations of outstanding invoice records.

When to use:

• When customer deposits consolidate multiple invoices or split remittances.

• When one-to-one or one-to-many heuristics leave unmatched aggregates.

When NOT to use:

• Do NOT use for straightforward 1:1 or 1:N reconciliation where reconcile is sufficient and faster.

• Do NOT use without the optional ilp extra installed (pip install reconcile-mcp[ilp]).

Behavioral transparency: Deterministic ILP optimization; read-only and idempotent.