pain001-mcp

Simulate payment batch

simulate_payment_batch

Read-onlyIdempotent

Pre-flight a payment batch before XML generation by validating records against schema and optional scheme rules, computing currency totals, and detecting duplicate transactions.

Instructions

Simulate and pre-flight a payment batch before XML generation.

Performs comprehensive pre-flight verification without generating XML
or staging files:

1. Validates records against the message type's JSON Schema.
2. Validates records against an optional payment-scheme rulebook.
3. Computes control sums grouped by currency.
4. Calculates unique debtor and creditor account counts.
5. Detects intra-batch duplicate transactions (same debtor, creditor,
   amount, currency, and execution date).

Returns a structured verdict with totals, sums by currency, duplicate
findings, and schema/scheme errors.

Args:
    message_type: A supported ISO 20022 pain message type.
    records: One or more flat payment records to simulate.
    scheme: Optional payment scheme profile to validate against.

Input Schema

Name	Required	Description
`scheme`	No	Optional payment-scheme rulebook profile to enforce (e.g. 'sepa-sct', 'sepa-sdd', 'sepa-inst', 'xborder-ct'). Omit to skip scheme-specific rulebook validation.
`records`	Yes	One or more flat payment records to simulate and pre-flight before generating XML. One or more flat payment records (dicts of field name → value). Key fields (see get_input_schema for the full contract): id, date (payment-initiation timestamp; 'YYYY-MM-DD' is accepted and rendered as midnight), initiator_name, payment_id, requested_execution_date ('YYYY-MM-DD'), debtor_name, debtor_account_IBAN, debtor_agent_BIC, creditor_name, creditor_account_IBAN, creditor_agent_BIC, payment_amount (alias: 'amount'; max two decimals), currency (alias: 'payment_currency'; ISO 4217, e.g. 'EUR'), remittance_information. batch_booking accepts JSON true/false. nb_of_txs and ctrl_sum are computed automatically from the records and may be omitted. payment_method defaults to 'TRF' and charge_bearer to 'SLEV'. IBAN and BIC values are strictly validated and never coerced.
`message_type`	Yes	A supported ISO 20022 pain message type. Must be exactly one of: 'pain.001.001.03', 'pain.001.001.04', 'pain.001.001.05', 'pain.001.001.06', 'pain.001.001.07', 'pain.001.001.08', 'pain.001.001.09', 'pain.001.001.10', 'pain.001.001.11', 'pain.001.001.12', 'pain.001.001.13', 'pain.008.001.02', 'pain.008.001.08', 'pain.001', 'pain.008' (see list_message_types). The bare family names 'pain.001' and 'pain.008' are accepted as aliases for 'pain.001.001.09' and 'pain.008.001.02'.

Output Schema

Name	Required	Description	Default
`error`	No
`total`	No
`valid`	No
`duplicates`	No
`valid_count`	No
`schema_errors`	No
`unique_debtors`	No
`unique_creditors`	No
`scheme_violations`	No
`control_sum_by_currency`	No

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.0.72Oct 1, 2026

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds real value beyond that by confirming no XML is generated and no files are staged. It also discloses the return shape (verdict with totals, sums by currency, duplicate findings, schema/scheme errors). It does not discuss failure modes or performance limits, keeping it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded, the numbered list of checks is scannable, and each item earns its place. The trailing Args block largely duplicates the fully-covered schema and could be dropped, which is the only waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a three-parameter, non-mutating simulation tool with an output schema, the description covers what is checked, what is not done (no XML, no staging), and what comes back. Nothing needed to invoke or interpret it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the schema documents scheme aliases, message_type enum, and record fields far more richly than the description. The Args block merely restates each parameter, adding only the word 'optional' for scheme, so it meets the baseline without exceeding it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (simulate/pre-flight) on a specific resource (payment batch) and enumerates the five concrete checks performed. The clause 'without generating XML or staging files' implicitly separates it from generate_message and stage_payment_batch, so an agent can place it precisely.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'before XML generation' framing gives clear usage context, and the negation of staging/generation rules out the write-flow siblings. However, it never explicitly says when to prefer this over validate_records, validate_payment_scheme, or simulate_clearing, which overlap substantially in this sibling set.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.