Skip to main content
Glama

ibanforge

by io.github.cammac-creator

Validate Payment Reference

validate_payment_reference
Read-onlyIdempotent

Validate a structured payment reference and, when an IBAN is supplied, decide whether the two may legally travel together. USE WHEN: assembling a payment instruction from an invoice, a QR-bill or a remittance advice; whenever a Swiss IBAN and a reference appear together (the pairing rule is what most integrations get wrong); or when the user pastes an "RF..." string, a 27-digit number, a +++123/4567/89012+++ block, or asks whether a payment reference is correct. DO NOT USE to validate the IBAN itself — that is validate_iban. SCHEMES: RF Creditor Reference (ISO 11649, "SCOR" in Swiss Payment Standards, mod 97-10); Swiss QR reference ("QRR", 27 digits, modulo 10 recursive); Belgian OGM/VCS (12 digits, modulo 97, a remainder of 0 written 97); Finnish viitenumero (4-20 digits, weights 7-3-1 from the right). Norwegian KID and Swedish OCR are RECOGNISED but never judged: they answer valid: null with status unverifiable_without_creditor_config, because modulus type and length are configured per creditor account by the beneficiary bank and are not a property of the string. NEVER relay those to a user as "invalid" — say the check needs the creditor bank configuration. AMBIGUITY: only a leading "RF" and a 27-digit length pin a scheme down. A bare 12-digit string is both a Belgian OGM and a legal Finnish length, so the more specific reading is returned and the other appears in also_valid_as. Pass reference_type when you know the country. THE PAIRING RULE — the part no checksum library reproduces: pass an iban and you also get a pairing verdict. Per the Swiss Implementation Guidelines a QRR reference may ONLY be used with a QR-IBAN (institution identifier in the SIX range 30000-31999), and an ISO 11649 reference may NOT be used with one. Outside CH and LI, pairing is not_applicable — there is no QR-IBAN to pair against — and that does not affect the reference's own checksum verdict. IMPORTANT: valid and pairing are INDEPENDENT. A reference can be arithmetically valid and still illegal on that account. Read both, and relay source/as_of — they are what makes the verdict auditable. FREE: the checksums are published commodities. The paid surface is POST /v1/iban/validate, which returns this same pairing block with the full IBAN enrichment. COST: $0 per call, on every surface (free: 10 units/IP/day on this transport, one per call and one per IBAN in batch_validate_iban, or a free API key at POST https://api.ibanforge.com/v1/keys/generate for 200 REST calls/month).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
ibanNoOptional creditor IBAN — supply it to get the pairing verdict
referenceYesThe reference as printed; spaces, slashes and the +++…+++ wrapper are stripped
reference_typeNoOptional hint: rf | scor | qrr | ogm | vcs | viitenumero | kid | ocr

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
noteYesWhat was checked, and what was not.
as_ofNoYYYY-MM of that document.
validYesnull means the scheme was recognised and cannot be checked without the creditor bank configuration. Never report null as false.
schemeYesrf | qrr | ogm | viitenumero | kid | ocr, or null when nothing matched.
sourceYesThe document publishing the rule. Null only when no scheme matched. Relay it.
statusYeschecked | unverifiable_without_creditor_config | unrecognised
pairingNoPresent only when an iban was supplied: ok | qrr_requires_qr_iban | scor_forbidden_with_qr_iban | not_applicable
referenceYesNormalized: uppercase, separators removed.
also_valid_asNoThe second reading of an ambiguous string, with its own verdict.
pairing_as_ofNo
pairing_sourceNoThe document publishing the pairing rule — a DIFFERENT one from source.
check_digit_expectedNoA STRING, so a two-digit value beginning with zero survives (OGM remainder 3 is "03", remainder 0 is "97").

Schema Changelog

Changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. Changed6 schema fields changed
    • removedOutput schema / properties / scheme / anyOf
      Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedOutput schema / properties / scheme / type
      Added value: +[
+  "string",
+  "null"
+]
    • removedOutput schema / properties / source / anyOf
      Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedOutput schema / properties / source / type
      Added value: +[
+  "string",
+  "null"
+]
    • removedOutput schema / properties / valid / anyOf
      Removed value: -[
-  {
-    "type": "boolean"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedOutput schema / properties / valid / type
      Added value: +[
+  "boolean",
+  "null"
+]
  2. Added

TDQS

A5/5.0
Behavior5/5

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

Annotations declare readOnlyHint=true and idempotentHint=true; the description goes far beyond by disclosing the independent valid/pairing verdicts, the unverifiable_without_creditor_config status for KID/OCR, and the ambiguity-resolution behavior (also_valid_as). It also explicitly warns not to call an unverifiable KID/OCR 'invalid,' which is a critical behavioral trait. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long, but every section earns its place: USE WHEN, DO NOT USE, scheme specifics, ambiguity rules, pairing rule, cost model. It is front-loaded with the primary purpose and most critical operational guidance. The structure uses clear capital-letter section labels and short imperative sentences, making it scannable despite its density.

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 tool is complex with multiple schemes, pairing logic, and edge cases; the description covers all meaningful behavioral aspects, including the return fields (valid, pairing, source/as_of), the cost ($0, free tier quotas), and how it fits with sibling tools. Since an output schema exists, the description doesn't need to enumerate return fields, but it mentions the auditable fields, making it complete for an agent to decide and correctly interpret results.

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

Parameters5/5

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

Although schema descriptions cover 100% of the 3 parameters, the description enriches meaning for each: reference explains stripping of spaces/slashes/+++ wrapper; iban's connection to the pairing rule is clarified; reference_type is given a usage hint ('Pass reference_type when you know the country') and a list of allowed values. The description also explains the interaction between iban and reference types, which no schema field could express.

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?

Description opens with a specific verb-resource pair: 'Validate a structured payment reference and, when an IBAN is supplied, decide whether the two may legally travel together.' It clearly distinguishes from the sibling validate_iban by stating 'DO NOT USE to validate the IBAN itself — that is validate_iban.' The use cases (invoice, QR-bill, remittance advice) further define the tool's scope.

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 provides explicit USE WHEN scenarios, a DO NOT USE directive with the exact alternative tool name, and even explains the boundary for recognized-but-unverifiable schemes (Norwegian KID, Swedish OCR). It tells the agent exactly when to invoke this tool versus validate_iban, and when not to relay an unverifiable result as invalid.

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

All ibanforge toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.5/5.0
Disambiguation4/5

Each tool has a distinct job, and the descriptions provide strong USE WHEN/DO NOT USE cues. The only plausible boundary cases are validate_iban vs batch_validate_iban (single vs bulk) and validate_iban vs check_compliance (general enrichment vs payment-risk triage), but both are clearly signposted.

Naming Consistency5/5

All tool names follow a consistent snake_case verb_noun pattern: validate_iban, check_compliance, lookup_bic, send_feedback, etc. batch_validate_iban reads as a compound verb + object and does not break the convention, and the verb choice also aligns with intent: validate for format checks, check for rule/risk checks, lookup for directory data.

Tool Count5/5

Eight tools are well-scoped for an IBAN validation and payment-intelligence API: single/batch validation, compliance, address rules, reference validation, BIC and Swiss clearing lookups, and feedback. Each tool carries a distinct capability and none feels redundant or padding.

Completeness5/5

The surface covers the full IBAN-informed workflow: validation, enrichment, batch processing, BIC/Swiss clearing resolution, payment-reference pairing, postal-address rail rules, and pre-payment compliance triage. Explicit limitations such as not verifying account existence or payee identity are domain constraints, not missing tools.

Resources