pain001-mcp

Simulate clearing network execution

simulate_clearing

Read-onlyIdempotent

Simulate settlement and clearing for a staged payment batch across EPC-SEPA, FedNow, US-ACH, SWIFT-MX, CHAPS, or BACS to verify eligibility, routing, cut-offs, and settlement windows.

Instructions

Simulate settlement and clearing network execution for a staged batch.

Evaluates network-specific rulebooks and clearing constraints:
- EPC-SEPA: EUR currency mandate, SEPA-zone IBAN prefixes, SLEV charge bearer.
- FedNow: USD instant gross settlement eligibility.
- US-ACH: USD next-day clearing cycle routing.
- SWIFT-MX: Cross-border correspondent banking BIC routing.
- CHAPS: Same-day RTGS high-value GBP clearing.
- BACS: Three-day GBP direct credit clearing.

Args:
    stage_id: Staging identifier from stage_payment_batch.
    clearing_system: Clearing rail profile to simulate.

Returns:
    SimulateClearingResult with verdict (ACCEPTED / REJECTED), detailed
    checks, and estimated settlement window, or {"error": ...}.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`stage_id`	Yes	The staging identifier returned by stage_payment_batch.
`clearing_system`	No	Target clearing system simulation profile to evaluate settlement eligibility, cut-off windows, and routing constraints.	EPC-SEPA

Output Schema

TableJSON Schema

Name	Required	Description	Default
`error`	No
`checks`	No
`stage_id`	No
`clearing_status`	No
`clearing_system`	No
`settlement_window`	No

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.0.72Oct 1, 2026

TDQS

A3.8/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true and non-destructive, so the safe, repeatable nature is covered. The description adds genuine context beyond that: it discloses that it evaluates network-specific rulebooks (per-rail currency/IBAN/charge-bearer/cut-off constraints) and the shape of the outcome (verdict, checks, settlement window, error).

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, then uses bullets efficiently to convey per-rail semantics that would otherwise be opaque enum values. The trailing Args/Returns block largely duplicates the input schema and the output schema, which is minor waste rather than a structural flaw.

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

Completeness4/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 return detail is optional but harmless; the annotations cover safety. The description supplies the domain context an agent needs (rail-specific rule profiles, staged-batch input) to invoke it correctly, leaving only the sibling-boundary with simulate_payment_batch unaddressed.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline would be 3, but the description adds real meaning to the clearing_system enum by spelling out what each rail enforces (EPC-SEPA EUR+IBAN+SLEV, FedNow instant gross, US-ACH next-day, SWIFT-MX BIC routing, CHAPS RTGS, BACS three-day), helping the agent choose a profile. The stage_id note merely restates the schema.

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 (simulate) and resource (settlement and clearing network execution) scoped to 'a staged batch', plus a concrete per-rail breakdown. It is clearly distinct from validation/generation siblings, though it never names the nearest sibling, simulate_payment_batch, to draw the boundary explicitly.

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

Usage Guidelines3/5

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

Usage is only implied: it works on 'a staged batch' whose stage_id comes from stage_payment_batch, and each rail's intended use case is sketched. There is no explicit when-to-use-this-vs-simulate_payment_batch guidance and no exclusions or prerequisites stated.

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