Aether Layer: EU VAT number validation (VIES)

Validate an EU VAT number

validate_vat

Read-onlyIdempotent

Validate an EU VAT number (27 member states + XI Northern Ireland). Normalizes the input, checks the national format and checksum locally, then queries VIES (European Commission) live with limited retries. status: valid | invalid (local checksum/format failed, or VIES answered valid=false) | unverified_ms_down (the member state system is down) | unverified. Results are cached across instances to respect VIES rules: valid/invalid 24 h, unverified 10 min; checked_at = time of the original VIES check, cache_age_s = its age in seconds. Never returns invalid because VIES is unavailable. The VIES name/address are never returned: pass your own name and/or address to get name_match / address_match booleans, computed locally (not sent to VIES; null when VIES has no data). Requires an API key in Authorization: Bearer or X-Api-Key. Controllo automatico: regole locali di formato e checksum più una consultazione live del VIES (Commissione europea). Non è un'attestazione fiscale né una consulenza legale; i dati VIES provengono dalle banche dati degli Stati membri. Conserva una tua traccia della consultazione VIES. / Automated check: local format/checksum rules plus a live query of VIES (European Commission). Not a tax attestation and not legal advice; VIES data come from the member states' databases. Keep your own record of the VIES consultation. / Automatische Prüfung: lokale Format- und Prüfziffernregeln plus eine Live-Abfrage von VIES (Europäische Kommission). Keine steuerliche Bescheinigung und keine Rechtsberatung; die VIES-Daten stammen aus den Datenbanken der Mitgliedstaaten. Bewahren Sie einen eigenen Nachweis der VIES-Abfrage auf.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "vat_id": "<vat_id>"
    },
    "name": "validate_vat"
  }
}

Input Schema

Name	Required	Description
`name`	No	Optional company name to compare with the VIES record (local match, not sent to VIES, not stored). Returns name_match.
`client`	No	Optional integration id <name>/<version>, e.g. shopware-plugin/0.1. Adoption metric only.
`vat_id`	Yes	VAT number with country prefix, e.g. IT00905811006, DE143454214, EL094014201 (GR accepted), XI…; spaces, dots and dashes are ignored.
`address`	No	Optional address to compare with the VIES record (local match, not sent to VIES, not stored). Returns address_match.
`country`	No	Optional ISO prefix when vat_id has none (e.g. IT).

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 12, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Goes well beyond the annotations (readOnly/openWorld/idempotent/non-destructive) by disclosing the two-stage check with limited retries, the full status vocabulary including 'unverified_ms_down', cache TTLs (24 h / 10 min), and the semantics of checked_at vs cache_age_s. It also states a key safety guarantee ('Never returns invalid because VIES is unavailable'), that name/address are never returned or sent to VIES, and that an API key via Authorization: Bearer or X-Api-Key is required — all information an agent cannot get from structured fields.

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

Conciseness2/5

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

The English lead is front-loaded and dense, but the disclaimer block is repeated three times in Italian, English, and German with near-identical content, roughly doubling the length without adding new information. Trimming to one language would materially reduce token cost with no loss of meaning.

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?

With no output schema, the description carries the return burden and does so fully: it enumerates every status value, explains the timing fields, and documents the derived match booleans. Auth requirements, caching behaviour, and the offline-fallback semantics are all covered, leaving nothing an agent needs in order to call and interpret 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: it clarifies that name/address are compared locally to produce name_match/address_match (null when VIES has no data) rather than being transmitted. It does not add anything about the 'client' adoption-metric field or country-prefix precedence beyond what the schema already says.

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 precise verb+resource+scope: 'Validate an EU VAT number (27 member states + XI Northern Ireland).' It also states the mechanism (local format/checksum plus live VIES query), so an agent knows exactly what operation it is calling. The only sibling, agent_readiness_check, is unrelated, so no differentiation is needed.

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?

The description gives clear operating context: when you want a name/address cross-check, 'pass your own name and/or address to get name_match / address_match booleans', and it warns that results are 'not a tax attestation and not legal advice'. It stops short of explicit when-to-use/when-not rules or naming an alternative path, so it is strong but not a 5.

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

All Aether Layer: EU VAT number validation (VIES) tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?