pain001-mcp

Migrate records between versions

migrate_records

Read-onlyIdempotent

Migrate flat payment records to a different pain.001 version, reporting renamed, derived, or dropped fields. Use to meet bank requirements, then validate and generate XML.

Instructions

Migrate flat payment records between two pain.001 schema versions.

Use this to upgrade/downgrade records when your bank requires a
different pain.001 version than your source data uses (e.g. move
``.03`` rows to ``.09``); it reports which fields were renamed, derived,
or dropped. This transforms records only — run ``validate_records``
afterwards, then ``generate_message`` to emit XML.

Wraps :class:`pain001.migration.VersionMapper`. Returns the
migrated rows plus a summary of which fields were renamed,
derived, or dropped; ``{"error": ...}`` if either version is
unsupported.

Args:
    records: Records in the ``from_version`` shape.
    from_version: Source pain.001 version (e.g. ``"pain.001.001.03"``).
    to_version: Target pain.001 version (e.g. ``"pain.001.001.09"``).

Returns:
    ``{"records": [...], "migrated": int, "from": str, "to": str}``
    or ``{"error": ...}``.

Input Schema

TableJSON Schema

Name	Required	Description
`records`	Yes	Flat payment records in the from_version shape, each a dict of field name → value, to transform to to_version.
`to_version`	Yes	Target pain.001 schema version to migrate the records to, e.g. 'pain.001.001.09' — see list_message_types.
`from_version`	Yes	Source pain.001 schema version the records currently use, e.g. 'pain.001.001.03' — see list_message_types.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`to`	No
`from`	No
`error`	No
`records`	No
`migrated`	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": "Records rewritten from one message edition to another.",
+  "properties": {
+    "error": {
+      "title": "Error",
+      "type": "string"
+    },
+    "from": {
+      "title": "From",
+      "type": "string"
+    },
+    "migrated": {
+      "title": "Migrated",
+      "type": "integer"
+    },
+    "records": {
+      "items": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "title": "Records",
+      "type": "array"
+    },
+    "to": {
+      "title": "To",
+      "type": "string"
+    }
+  },
+  "title": "MigrateResult",
+  "type": "object"
+}

Changed3 schema fields changedv0.0.56Jul 10, 2026

addedInput schema / properties / from_version / description

Added value: +"Source pain.001 schema version the records currently use, e.g. 'pain.001.001.03' — see list_message_types."

addedInput schema / properties / records / description

Added value: +"Flat payment records in the from_version shape, each a dict of field name → value, to transform to to_version."

addedInput schema / properties / to_version / description

Added value: +"Target pain.001 schema version to migrate the records to, e.g. 'pain.001.001.09' — see list_message_types."

First observedJul 9, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Annotations already establish readOnly, idempotent, and non-destructive behavior. The description adds real behavioral context beyond that: it reports renamed/derived/dropped fields, returns migrated rows plus a summary, and returns an error object if either version is unsupported. The 'transforms records only' statement clarifies there is no persistent side effect.

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 workflow, then return contract. It is readable and well organized, though somewhat redundant: the renamed/derived/dropped summary appears twice, and the Args/Returns sections duplicate the input schema and output schema rather than adding new information.

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 transformation tool with rich annotations and an output schema, the description is complete. It covers the trigger condition, the transformation semantics, the error case, the return shape, and the correct surrounding workflow with validate_records and generate_message. Nothing needed to invoke 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%, so the baseline is 3 even without extra parameter detail. The description's Args section mostly repeats the schema, and the examples it adds ('pain.001.001.03', 'pain.001.001.09') are already present in the schema. It does not meaningfully compensate beyond what the structured schema already documents.

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 opens with a specific verb and resource: 'Migrate flat payment records between two pain.001 schema versions.' It clearly distinguishes itself from siblings by noting it 'transforms records only' and naming the downstream validate_records/generate_message steps, so an agent can tell this apart from XML generation or validation tools.

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?

It gives a clear trigger condition: use when a bank requires a different pain.001 version than the source data uses, with a concrete .03-to-.09 example. It also prescribes the follow-up workflow ('run validate_records afterwards, then generate_message'), but it does not explicitly mention alternatives or when not to use this tool, such as the sibling convert_mt101.

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