pain001-mcp

Simulate payment batch

simulate_payment_batch

Read-onlyIdempotent

Simulate and pre-flight a payment batch before XML generation: validate records against ISO 20022 schemas and scheme rules, compute control sums, and detect duplicates.

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

TableJSON 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

TableJSON 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, and the description usefully adds that no XML is generated and no files are staged, plus it outlines the internal checks and the returned verdict. It does not cover permissions, rate limits, or cost, so it adds solid but not exhaustive context.

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?

Front-loaded one-line summary followed by a scannable numbered list of the five verifications is well structured. The trailing Args section largely duplicates schema content and is the one redundant element.

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?

Given an output schema exists, the description need not detail return values, yet it still states a structured verdict with totals, per-currency sums, duplicates, and errors. Combined with the explicit no-side-effect statement, it is complete for correct invocation.

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 itself documents scheme, records (with aliases, formats, defaults), and message_type in rich detail, including the bare-family aliases. The description's Args block only restates these minimally, adding no meaning beyond the schema, so the baseline 3 applies.

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) and resource (payment batch) and enumerates the five concrete checks performed. This clearly distinguishes it from siblings like validate_records, stage_payment_batch, and generate_message.

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?

Positions the tool precisely: 'pre-flight a payment batch before XML generation' and 'without generating XML or staging files,' which implicitly routes agents away from stage_payment_batch/generate_message for dry-run checks. It never explicitly names those alternatives or states when-not to use it, so a full 5 is not earned.

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