pain001-mcp

Stage payment batch for simulation and approval

stage_payment_batch

Stage an ISO 20022 payment batch in memory for simulation and dual-control approval, with schema and scheme validation, risk scoring, fee checks, fingerprinting, and a confirmation token.

Instructions

Stage a payment batch for simulation and dual-control approval.

Creates an in-memory staged payment order with zero fund movement and
a 1-hour expiration window. Computes:

1. Schema validation against the message type's JSON Schema.
2. Optional scheme compliance verification (SEPA, BACS, etc.).
3. Multi-currency control sums and fee estimation.
4. Multi-factor risk scoring (detecting duplicates, high transaction
   amounts, and generic remittance narratives).
5. In-memory XML compilation and SHA-256 fingerprinting.
6. Cryptographic dual-control confirmation token for subsequent authorization.

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

Returns:
    StagedBatchResult with staging metadata, risk assessment, fingerprint,
    and confirmation token, or {"error": ...}.

Input Schema

Name	Required	Description
`scheme`	No	Optional payment scheme profile to validate against, e.g. 'sepa-sct', 'sepa-instant', 'bacs', or 'cbpr-plus'.
`records`	Yes	Flat payment records to stage (zero fund movement). 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
`status`	No
`stage_id`	No
`expires_at`	No
`risk_level`	No
`risk_score`	No
`risk_factors`	No
`estimated_fees`	No
`confirmation_token`	No
`sha256_fingerprint`	No
`total_transactions`	No
`control_sum_by_currency`	No

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.0.72Oct 1, 2026

TDQS

A4.1/5.0

Behavior5/5

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

Goes well beyond the annotations by disclosing that state is in-memory only, expires after 1 hour, moves no funds, and enumerates the six computations performed (schema validation, scheme compliance, fee/control-sum, risk scoring, XML fingerprinting, dual-control token). It also states the error return shape, giving an agent a complete picture of a mutating-but-harmless operation.

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-loads the purpose and key safety property ('zero fund movement', 1-hour expiry) before the numbered breakdown, which is scannable. The Args section partly duplicates schema content, and the six-item list is longer than strictly needed, but each item conveys distinct behavior.

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 3-parameter tool with an output schema and full schema coverage, the description supplies everything an agent needs: lifecycle semantics (staging → token → authorization), what is computed, and the error form. Nothing material 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 itself already documents records field aliases, defaults, and the enum list; the description's Args section largely restates those three parameters at a higher level. Baseline 3 applies since the schema does the heavy lifting and the description adds no new parameter constraints.

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

Purpose4/5

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

States a specific verb and resource ('Stage a payment batch') plus scope ('in-memory', 'zero fund movement', 1-hour expiration), which clearly separates it from a real commit. It does not explicitly name the sibling it hands off to (commit_payment_batch) or the simulate_payment_batch alternative, so sibling differentiation is implied rather than stated.

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?

Gives clear usage context: it is a pre-authorization staging step with no fund movement, producing a token 'for subsequent authorization'. It does not say when to prefer this over simulate_payment_batch or commit_payment_batch, or when staging is inappropriate (e.g. large batch limits), so no explicit exclusions.

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