Use this first, before any validation or generation call, to discover the
exact ``message_type`` strings this server accepts. For the return-reason
codes rather than message types, call ``list_return_reasons`` instead.

Returns a list of ``{"message_type": ..., "name": ...}`` dictionaries, one
per supported message type (e.g. ``camt.053.001.14``).

Use this to discover the ``reason_code`` values that ``filter_entries`` and
``generate_reversal`` accept (e.g. ``AC04`` Closed Account). For the
supported message types rather than reason codes, use ``list_message_types``.

Returns a list of ``{"code": ..., "name": ...}`` dictionaries (e.g.
``{"code": "AC04", "name": "Closed Account Number"}``).

Use this for a quick checklist of the mandatory columns before building
reversing-entry records. When you need full type/format constraints (not
just which fields are required), call ``get_input_schema`` instead.

Args:
    message_type: A supported ISO 20022 camt.05x message type.

Use this to learn every field, its type, and its constraints before
assembling records, or to drive a form/UI. For just the required-field
names use ``get_required_fields``; to actually check records against this
schema use ``validate_records``.

Args:
    message_type: A supported ISO 20022 camt.05x message type.

Use this on in-memory reversing-entry records to catch structural/type
errors per row before generation. To validate a whole camt.05x *document*
(XML) against its XSD instead, use ``validate_statement``.

Returns a report ``{"valid": bool, "total": int, "valid_count": int,
"errors": [...]}``.

Args:
    message_type: A supported ISO 20022 camt.05x message type.
    records: One or more flat reversing-entry records to validate.

Use this for a one-off identifier check with a clear pass/fail. To validate
identifiers embedded across a whole batch of records, prefer
``validate_records`` rather than calling this per field.

Returns ``{"kind": str, "value": str, "valid": bool}``.

Args:
    kind: One of ``"iban"``, ``"bic"``, or ``"lei"`` (case-insensitive).
    value: The identifier value to check.

Use this to turn a raw statement into a navigable dict (header, statements,
accounts, balances, entries). To pull just the flat entry list use
``list_entries``; to only check the document is schema-valid use
``validate_statement``.

Returns the parsed document as a JSON-serialisable dict (group header plus
statements, each with its account, balances, and entries), or an
``{"error": ...}`` payload if the XML cannot be parsed.

Args:
    xml: The raw statement XML as a string.

Use this to confirm a document is well-formed and schema-valid before
processing it. This checks XSD conformance only; for the Nov 2026 CBPR+
business rules use ``check_cbpr_readiness``, and to extract the data use
``parse_statement``.

Detects the document's message type, validates it against the matching
ISO 20022 schema, and returns a report ``{"valid": bool, "message_type":
str, "errors": [...]}``. A well-formed but schema-invalid document yields
``valid=False`` with a populated ``errors`` list (and the detected
``message_type``); a valid one yields ``valid=True`` with no errors.

Returns an ``{"error": ...}`` payload instead if the XML cannot be parsed
(e.g. it is malformed or is not a camt ``Document``).

Args:
    xml: The raw statement XML as a string.

Use this to audit a statement for the business-rule changes (schema
version, structured postal addresses) enforced from the Nov 2026 cutover.
For plain XSD schema validity use ``validate_statement`` instead; for just
the cutover date use ``get_cbpr_cutover_date``.

A coordinated CBPR+ / Fedwire / CHAPS / T2 cutover lands on
**14-16 November 2026**: unstructured-only postal addresses get rejected,
``camt.110/111`` exceptions and investigations become mandatory, and T2S
R2026.NOV upgrades camt.053 / 054 to schema revision MR2026.

This tool walks the supplied payload and reports every issue that will
fail the Nov 2026 acceptance rules:

* **Schema version** vs the CBPR+ current set (``camt.053.001.08`` /
  ``camt.053.001.13``); ``.02``-``.07`` are flagged as deprecated
  warnings; unknown / non-camt.053 namespaces as errors.
* **Postal addresses**: every ``<PstlAdr>`` is classified as fully
  structured, hybrid, or **unstructured-only** (``<AdrLine>`` without
  ``<TwnNm>`` + ``<Ctry>`` siblings, the Nov 2026 reject case).

Returns a dictionary ``{"cbpr_ready": bool, "schema_version": str | None,
"checked_at": ISO-8601 UTC, "cutover_date": "2026-11-16",
"issues": [...], "summary": {...}}``. ``cbpr_ready`` is ``True`` iff no
``severity="error"`` issue was raised. An ``{"error": ...}`` envelope
is returned instead if the XML is malformed or refused by the
hardened pre-flight (DOCTYPE / ENTITY / oversized payload).

Args:
    xml: The raw camt.05x statement XML as a string.

Use this to quote the enforcement date directly, without parsing a
document. To actually audit a statement against the rules that take effect
on that date, call ``check_cbpr_readiness`` instead.

The cutover (``2026-11-16``) is the date after which the rules checked
by ``check_cbpr_readiness`` are enforced by the major clearing systems;
payments that fail will be rejected at receive-time. Surfaced as a
discrete tool so agents can quote it directly without having to call
a readiness check first.

Use this to quote one specific rule (with its canonical source URL) once
you know the ``scheme``/``version``/``clause``. To discover which clauses
exist first, call ``list_rulebook_clauses``.

Looks up one well-known rule across the SEPA, CBPR+, and HVPS+
rulebooks and returns a short summary together with the canonical
source URL so an agent can quote the rule and the operator can
verify it against the official document.

The registry is a curated convenience layer, not a verbatim
reproduction of copyrighted text. Always defer to ``source_url``
for authoritative wording before relying on a citation for
compliance or contractual decisions; the returned ``disclaimer``
field repeats this for the calling agent.

Args:
    scheme: One of ``"SEPA"``, ``"CBPR+"``, or ``"HVPS+"`` (case
        sensitive).
    version: The rulebook version (e.g. ``"2025"`` or ``"2026"``).
    clause: A kebab-case clause identifier from
        ``list_rulebook_clauses``.

Returns:
    A citation dict ``{"scheme", "version", "clause", "title",
    "summary", "source_url", "as_of", "disclaimer"}`` or an
    ``{"error": ...}`` payload if the citation is not in the
    registry.

Use this to browse the citation registry and pick a ``clause`` id; then pass
that id to ``cite_rulebook`` to fetch the full summary and source URL.

Returns the full registry, optionally filtered by ``scheme`` and /
or ``version``. Use the resulting ``clause`` values as input to
``cite_rulebook``.

Args:
    scheme: Restrict to one scheme (e.g. ``"SEPA"``). ``None``
        returns all schemes.
    version: Restrict to one version (e.g. ``"2026"``). ``None``
        returns all versions.

Use this to reshape a statement's booked entries into ready-to-POST Xero or
QuickBooks payloads (the tool builds the payloads only; it does not call any
external API or write files). To discover the valid ``target`` values first,
call ``list_export_journal_targets``.

Parses the supplied statement and re-shapes every booked entry
into a target-specific journal-entry payload ready for direct
POST to the accounting platform's REST API.

Supported targets (see ``camt053_mcp.export_journal.SUPPORTED_TARGETS``):

* ``"xero"`` - returns a list of Xero ``BankTransactions``
  payloads. Each entry maps to ``{Type, Reference, Date,
  BankAccount, Contact, LineAmountTypes, CurrencyCode,
  LineItems}``; CRDT entries become ``Type=RECEIVE`` and DBIT
  entries ``Type=SPEND``.
* ``"qbo"`` - returns a list of QuickBooks Online
  ``JournalEntry`` payloads. Each entry produces a balanced
  two-line journal (one to the bank account, one to a clearing
  account; sign flipped on debit entries).

Operator-specific values (account codes, contact identifiers,
realm IDs) appear as ``"OPERATOR_FILL"`` placeholders so the
operator knows exactly what still needs wiring. The response's
``placeholder_count`` field reports the total.

NetSuite + SAP S/4HANA targets are tracked as a follow-up in #17.

Args:
    xml: The raw camt.053 statement XML as a string.
    target: One of ``"xero"`` or ``"qbo"`` (default ``"xero"``).

Returns:
    ``{"target", "entries", "placeholder_count", "placeholder_field"}``
    on success, or ``{"error": ...}`` on failure (unsupported
    target / malformed XML / parse refusal).

Use this to tell a user which ``target`` values ``export_journal`` accepts
before invoking it. This lists export destinations only; for the LLM
classifier's category vocabulary use ``list_classify_entry_categories``.

Returns the sorted list of valid ``target`` arguments accepted by
``export_journal`` (``["qbo", "xero"]`` today). NetSuite and SAP
S/4HANA support is a tracked follow-up.

Use this when you want a semantic, model-driven label for an entry (payroll,
fee, refund, …) rather than a deterministic rule match. Because it delegates
an LLM completion to the client it is open-world and non-idempotent; for the
fixed candidate categories it chooses from, call
``list_classify_entry_categories`` first.

Uses the **MCP Sampling** protocol primitive: the server (this
process) asks the *client* (the agent's host application) to
perform an LLM completion on the server's behalf, then receives
the model's structured response. Keeps every LLM call in the
operator's existing model contract (privacy, billing, audit).

The model is asked to choose exactly one category from
``categories`` (or :data:`camt053_mcp.classify.DEFAULT_CATEGORIES`
if ``None`` is passed) and return a structured
``{category, confidence, explanation}`` payload.

Clients that do not support Sampling will get an
``{"error": "..."}`` envelope and can fall back to a rules-only
classifier.

Args:
    ctx: The FastMCP Context (auto-injected; provides
        ``session.create_message``).
    entry: A statement entry dict (the shape returned by
        ``parse_statement`` / ``list_entries``).
    categories: The candidate categories. ``None`` uses the
        built-in default list (12 common payment buckets).

Returns:
    ``{"category", "confidence", "explanation"}`` on success or
    ``{"error": "..."}`` on Sampling failure / malformed model
    response / out-of-vocabulary category.

Use this to quote the built-in category vocabulary to a user before running
the LLM classifier. This is a static list lookup (no model call); to
actually classify an entry, call ``classify_entry``.

Operators can override the list per call; this tool exposes the
default the prompt template ships with so an agent can quote them
to the user before invoking the classifier.

Use this to get the flat, paginable entry list from a statement. To keep
only the entries carrying a given return-reason code use ``filter_entries``;
for the full nested document structure use ``parse_statement``.

When ``limit`` is ``None`` (the default) the full list of entries is
returned. When ``limit`` is given, a paginated envelope ``{"total",
"offset", "limit", "entries"}`` is returned instead, exposing the
``offset:offset + limit`` slice. A negative ``offset`` or ``limit`` yields
an ``{"error": ...}`` payload.

Args:
    xml: The raw statement XML as a string.
    offset: The zero-based index of the first entry to return (paginated
        mode only; default ``0``).
    limit: The maximum number of entries to return, or ``None`` for the
        full list (default ``None``).

Use this to preview exactly which entries a reversal would touch before
calling ``generate_reversal`` with the same ``reason_code``. For every entry
regardless of reason code use ``list_entries`` instead.

When ``limit`` is ``None`` (the default) the full list of matching entries
is returned, preserving the behaviour expected by existing callers. When
``limit`` is given, a paginated envelope ``{"total", "offset", "limit",
"entries"}`` is returned instead, exposing the ``offset:offset + limit``
slice. A negative ``offset`` or ``limit`` yields an ``{"error": ...}``
payload.

Args:
    xml: The raw statement XML as a string.
    reason_code: The ISO external return reason to match (default
        ``"AC04"`` Closed Account).
    offset: The zero-based index of the first entry to return (paginated
        mode only; default ``0``).
    limit: The maximum number of entries to return, or ``None`` for the
        full list (default ``None``).

This is the headline one-shot workflow: pass an incoming statement and a
return-reason code and get back the reversal XML (nothing is written to
disk). Preview which entries will be reversed first with ``filter_entries``
using the same ``reason_code``.

This is the headline one-shot workflow: parse the incoming camt.053, pick
the entries with the requested return reason (e.g. AC04 Closed Account),
and emit a validated camt.053.001.14 reversal statement.

Returns the validated XML document as a string, or an ``{"error": ...}``
payload (serialized) if generation fails.

Args:
    xml: The raw incoming statement XML as a string.
    reason_code: The ISO external return reason to reverse (default
        ``"AC04"``).