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").

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds extensive behavioral context beyond them: KID/OCR return valid:null with status unverifiable_without_creditor_config and must NEVER be relayed as 'invalid'; ambiguous 12-digit strings yield also_valid_as; the pairing rule is specified with the SIX range 30000-31999 and not_applicable outside CH/LI; valid and pairing are independent; and rate limits (10 units/IP/day) plus the free API key route are disclosed. 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.

Conciseness4/5

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

The purpose is front-loaded in the first sentence and the body is highly structured with scannable label sections (USE WHEN, SCHEMES, AMBIGUITY, THE PAIRING RULE, IMPORTANT, COST). It is long, but nearly every sentence carries decision-relevant content; only the closing FREE/COST passage drifts toward marketing and could be trimmed without losing invocation-critical 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 tool with genuine complexity — five checksum schemes, ambiguity resolution, a pairing rule, and an edge-case class (KID/OCR) that must not be mislabeled — the description covers every decision-relevant behavior: scheme algorithms, ambiguity handling, the pairing rule, independence of valid vs pairing, auditable source/as_of, and cost/rate limits. An output schema exists, so return-value documentation is not the description's burden; nothing needed to invoke this tool correctly is missing.

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 is 3; the description adds genuine meaning on top: passing iban triggers the pairing verdict and explains what that verdict means (QR-IBAN SIX range, ISO 11649 exclusion, not_applicable outside CH/LI), reference formats are tied to scheme-pinning rules (leading 'RF' and 27-digit length), and reference_type is framed as a country hint for disambiguation. This exceeds the schema's bare parameter descriptions.

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?

Opens with a specific verb and resource: 'Validate a structured payment reference and, when an IBAN is supplied, decide whether the two may legally travel together.' It names the exact schemes handled (RF, QRR, OGM/VCS, viitenumero, KID, OCR) and explicitly differentiates from the sibling validate_iban via 'DO NOT USE to validate the IBAN itself — that is validate_iban.' An agent cannot mistake what this tool does.

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?

Provides an explicit 'USE WHEN' list with concrete triggers (assembling a payment instruction from invoice/QR-bill/remittance advice, Swiss IBAN+reference pairing, pasted RF/27-digit/+++…+++ strings) and a 'DO NOT USE' exclusion that names the correct alternative (validate_iban). It also tells the agent to pass reference_type when the country is known, giving actionable selection guidance.

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