pain001-mcp

Sanitise text to ISO 20022 charset

sanitize_to_iso20022_charset

Read-onlyIdempotent

Transliterate accents and replace unsupported symbols in a free-text field to meet SWIFT/ISO 20022 character set rules. Choose SWIFT_X or SWIFT_Z, then get flags indicating validity and changes.

Instructions

Sanitise one free-text field to a SWIFT / ISO 20022 character set.

Use this on a single free-text value (name, remittance info) to
transliterate accents and drop unsupported symbols before placing it in
a record, and to see whether the value changed. Operates on one string;
to check a whole batch's rulebook compliance use ``validate_payment_scheme``.

Two character sets are supported via ``charset``:

* ``"SWIFT_X"`` (default, backward-compatible) - the basic set used in
  most ISO 20022 / pain.001 fields. Delegates to
  :func:`pain001.sanitize_to_charset`.
* ``"SWIFT_Z"`` - the SWIFT extended set, a strict superset of X that also
  permits ``= ! " % & * < > ; { @ # _`` (used in narrative / envelope
  fields). It does not permit ``|`` or ``}``.

In both cases accents are transliterated (``é`` -> ``e``) and any remaining
out-of-set character is replaced with a space. The result includes flags
for whether the original was already valid and whether it changed - useful
for surfacing the change to the user before writing it back to a record.

Args:
    value: The text to sanitise.
    charset: ``"SWIFT_X"`` (default) or ``"SWIFT_Z"``.

Returns:
    ``{"value": str, "sanitised": str, "was_valid": bool, "changed": bool}``.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`value`	Yes	A single free-text field value (e.g. a name or remittance line) to transliterate to the ISO 20022 Latin character set.
`charset`	No	Which SWIFT character set to sanitise against. 'SWIFT_X' (default) is the basic set permitted in most ISO 20022 / pain.001 fields: letters, digits, space and the punctuation / - ? : ( ) . , ' + . 'SWIFT_Z' is the extended superset that additionally allows = ! " % & * < > ; { @ # _ (used in narrative / envelope fields); it does NOT allow \| or }. Pick SWIFT_Z only when the target field is documented as Z-set.	SWIFT_X

Output Schema

TableJSON Schema

Name	Required	Description	Default
`value`	No
`changed`	No
`sanitised`	No
`was_valid`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.0.71Sep 26, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "description": "A value and its ISO 20022 charset-clean rendering.",
+  "properties": {
+    "changed": {
+      "title": "Changed",
+      "type": "boolean"
+    },
+    "sanitised": {
+      "title": "Sanitised",
+      "type": "string"
+    },
+    "value": {
+      "title": "Value",
+      "type": "string"
+    },
+    "was_valid": {
+      "title": "Was Valid",
+      "type": "boolean"
+    }
+  },
+  "title": "SanitiseResult",
+  "type": "object"
+}

Changed1 schema field changedv0.0.62Aug 22, 2026

addedInput schema / properties / charset

Added value: +{
+  "default": "SWIFT_X",
+  "description": "Which SWIFT character set to sanitise against. 'SWIFT_X' (default) is the basic set permitted in most ISO 20022 / pain.001 fields: letters, digits, space and the punctuation / - ? : ( ) . , ' + . 'SWIFT_Z' is the extended superset that additionally allows = ! \" % & * < > ; { @ # _ (used in narrative / envelope fields); it does NOT allow | or }. Pick SWIFT_Z only when the target field is documented as Z-set.",
+  "enum": [
+    "SWIFT_X",
+    "SWIFT_Z"
+  ],
+  "title": "Charset",
+  "type": "string"
+}

Addedv0.0.60Jul 18, 2026
RemovedJul 18, 2026

Changed1 schema field changedv0.0.56Jul 10, 2026

addedInput schema / properties / value / description

Added value: +"A single free-text field value (e.g. a name or remittance line) to transliterate to the ISO 20022 Latin character set."

First observedJul 9, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds valuable behavioral detail beyond the annotations: accents are transliterated, out-of-set characters are replaced with a space, and the result includes flags for validity and change. It also discloses charset limitations such as SWIFT_Z not permitting '|' or '}'.

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 description is front-loaded with purpose and usage, then uses clear bullets and an Args/Returns section. It is longer than strictly necessary—some charset details repeat what the schema already states—but every major section contributes to correct invocation, so the structure earns a strong score.

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?

The description covers the input value, both charset options, the transformation behavior, and the exact return shape. It also routes to the correct sibling for batch validation. With a rich output schema and safety-bearing annotations present, there are no meaningful gaps for an agent deciding whether and how to call this tool.

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 description coverage is 100%, so the parameter semantics are already well documented in the input schema. The description still adds value by framing charset as 'SWIFT_X' default and backward-compatible, noting SWIFT_Z is a strict superset, and clarifying the practical distinction between basic and extended character sets.

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?

The description states a specific verb and resource: 'Sanitise one free-text field to a SWIFT / ISO 20022 character set.' It clearly differentiates from the sibling tool validate_payment_scheme by noting that this operates on one string while that checks a whole batch's rulebook compliance. The two supported charsets are also explicitly named and contrasted.

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

Usage Guidelines5/5

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

The description gives explicit when-to-use guidance: apply this to a single free-text value before placing it in a record, and use it to surface whether the value changed. It also names the alternative for batch-level checks (validate_payment_scheme) and explains when to choose SWIFT_Z versus SWIFT_X, leaving no ambiguity about selection.

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