vat-validator-mcp 1.4.8 → 1.4.12

package/README.md

@@ -1,177 +1,83 @@
-[![smithery badge](https://smithery.ai/badge/OjasKord/vat-validator-mcp)](https://smithery.ai/servers/OjasKord/vat-validator-mcp)
+# VAT Validator MCP
 
-# VAT Validator MCP — Business Identity Verification & Invoice Fraud Detection
+**AI-powered VAT fraud detection and live VAT number validation
+for AI agents.**
 
-Validate EU, UK, and Australian VAT numbers against live government registries. Plus AI-powered fraud risk analysis and invoice verification — so your agent doesn't just know a VAT number is valid, it knows whether to proceed with the transaction.
+Validates EU, UK, and AU VAT numbers against authoritative live
+sources and uses AI pattern analysis to detect invoice fraud
+before payment is authorised. Built for compliance agents,
+invoice processing workflows, and supplier onboarding pipelines.
 
-**Free tier: 20 calls/month. No API key required. Just connect and go.**
+## What This Solves
 
-## Quick Start
+VAT fraud costs EU businesses €50bn annually. The most common
+attack vectors — missing trader fraud, carousel fraud,
+deregistered entity re-use — share one common signal: a VAT
+number that looks valid but isn't registered to the entity on
+the invoice.
 
-```json
-{
-  "vat-validator": {
-    "url": "https://vat-validator-mcp-production.up.railway.app"
-  }
-}
-```
-
-Or via Smithery:
-
-```bash
-npx -y @smithery/cli@latest mcp add OjasKord/vat-validator-mcp
-```
-
-## Why Use This
+Claude and other LLMs cannot reliably check live VAT registration
+status from training data. This tool calls the authoritative
+sources directly:
 
-A VAT number is the most reliable identifier for a registered business in the EU, UK, and Australia. Validating it confirms the company is real and legally registered. But validation alone isn't enough — scammers use valid VAT numbers with mismatched company names, or invoice from newly registered shells. The AI tools in this server catch what raw validation misses.
-
-Required for EU ViDA mandatory e-invoicing compliance from 2026.
+- **EU VIES** — all 27 member states, real-time
+- **UK HMRC VAT API v2** — OAuth2, authoritative
+- **AU ABR** — Australian Business Register
 
 ## Tools
 
-### `validate_vat`
-Validate any EU, UK, or Australian VAT number against live government registries. Auto-detects country from prefix. Use before any B2B transaction, supplier onboarding, or invoice approval.
-
-- EU (all 27 member states) via EU VIES (ec.europa.eu/taxation_customs/vies)
-- UK (GB prefix) via UK HMRC (api.service.hmrc.gov.uk)
-- Australia (AU prefix or 11-digit ABN) via Australian ABR (abr.business.gov.au)
-
-```json
-{ "vat_number": "DE811128135" }
-```
-
-### `validate_uk_vat`
-UK-specific validation against HMRC live records. Returns HMRC consultation number for audit trail. Use when you need to prove compliance during a tax audit.
-
-```json
-{ "vat_number": "GB123456789" }
-```
-
-### `get_vat_rates`
-Current VAT rates for all 27 EU member states, UK, and Australia. Use before generating any cross-border invoice or quote.
-
-```json
-{ "country_code": "DE" }
-```
-
-### `batch_validate` *(Paid only)*
-Validate up to 10 VAT numbers in one call across any mix of EU, UK, and Australian numbers. Use for supplier onboarding batches and monthly vendor audits.
-
-```json
-{ "vat_numbers": ["DE811128135", "GB123456789", "FR12345678901"] }
-```
-
-### `analyse_vat_risk` *(AI-powered — NOT a database lookup)*
-AI fraud risk assessment after validation. Returns CLEAR/REVIEW/BLOCK recommendation with specific fraud signals. Catches name mismatches between invoice and registry, newly registered companies with large invoice values, dormant status, shell company indicators, and address anomalies. Use before approving any payment or signing any contract with a first-time counterparty.
-
-```json
-{
-  "vat_number": "DE811128135",
-  "validation_result": { "valid": true, "company_name": null, "country": "DE" },
-  "invoice_amount": 50000,
-  "invoice_company_name": "Deutsche Test GmbH"
-}
-```
-
-### `compare_invoice_details` *(AI-powered — NOT a database lookup)*
-AI comparison of invoice details against official registry records. Flags discrepancies between the company name, address, and VAT number on an invoice versus registered government data. A name mismatch is one of the most common invoice fraud signals. Use before approving payment on any invoice from an unverified supplier.
-
-```json
-{
-  "invoice_company_name": "Deutsche Test GmbH",
-  "invoice_vat_number": "DE811128135",
-  "invoice_address": "Musterstrasse 1, Berlin",
-  "validation_result": { "valid": true, "company_name": null, "country": "DE" }
-}
-```
-
-## Example Responses
+| Tool | Free Tier | Use When |
+|---|---|---|
+| validate_vat | 20/month | Before approving any EU supplier or invoice |
+| validate_uk_vat | 20/month | Before approving any UK supplier or invoice |
+| get_vat_rates | 20/month | Before calculating cross-border invoice totals |
+| batch_validate | Paid | Validating a supplier list or invoice batch |
+| analyse_vat_risk | 20/month | Before approving any high-value cross-border invoice |
+| compare_invoice_details | 20/month | Before authorising payment on any supplier invoice |
 
-**validate_vat:**
-```json
-{
-  "valid": true,
-  "vat_number": "DE811128135",
-  "country": "DE",
-  "company_name": null,
-  "source": "VIES",
-  "source_url": "ec.europa.eu/taxation_customs/vies",
-  "checked_at": "2026-04-09T06:17:00Z"
-}
-```
+## Add to Your Agent
 
-**analyse_vat_risk:**
-```json
+**Claude Code** — add to .mcp.json:
 {
-  "recommendation": "REVIEW",
-  "risk_level": "MEDIUM",
-  "risk_score": 65,
-  "fraud_signals": ["Company name not available in registry despite valid VAT number", "Unable to verify invoice company name against registry data"],
-  "positive_indicators": ["VAT number validates as authentic in German registry"],
-  "recommended_action": "Request additional company documentation before processing payment.",
-  "summary": "Valid VAT number but missing registry information prevents full verification."
+  "mcpServers": {
+    "vat-validator": {
+      "type": "sse",
+      "url": "https://vat-validator-mcp-production.up.railway.app/sse"
+    }
+  }
 }
-```
-
-## Recommended Workflows
-
-**Invoice processing (3 calls):**
-1. `validate_vat` — confirm VAT number is real and active
-2. `compare_invoice_details` — AI checks invoice name/address against registry
-3. `analyse_vat_risk` — AI fraud risk assessment with CLEAR/REVIEW/BLOCK
-Only proceed with payment if recommendation is CLEAR.
-
-**Supplier onboarding (2 calls):**
-1. `validate_vat` — confirm registration
-2. `analyse_vat_risk` — AI fraud signal check
-
-**Monthly vendor audit (1 call):**
-- `batch_validate` — re-validate all active suppliers. Registrations can lapse.
-
-## Data Sources
-
-| Tool | Data Source | Update Frequency |
-|---|---|---|
-| validate_vat (EU) | EU VIES (ec.europa.eu/taxation_customs/vies) | Real-time |
-| validate_vat (UK) | UK HMRC (api.service.hmrc.gov.uk) | Real-time |
-| validate_vat (AU) | Australian ABR (abr.business.gov.au) | Real-time |
-| analyse_vat_risk | Registry data + Claude AI analysis | Real-time |
-| compare_invoice_details | Registry data + Claude AI analysis | Real-time |
-
-Every response includes `source_url` and `checked_at` so agents can verify exactly where data came from and when.
-
-## Supported Jurisdictions
 
-**EU (27 member states):** AT BE BG CY CZ DE DK EE EL ES FI FR HR HU IE IT LT LU LV MT NL PL PT RO SE SI SK
+**LangChain:**
+from langchain_mcp import MCPClient
+client = MCPClient(
+    "https://vat-validator-mcp-production.up.railway.app/sse"
+)
 
-**UK:** GB prefix via HMRC
-
-**Australia:** AU prefix or 11-digit ABN via ABR
+**OpenAI Agents SDK:**
+from agents.mcp import MCPServerSse
+mcp_server = MCPServerSse(
+    params={
+        "url": "https://vat-validator-mcp-production.up.railway.app/sse"
+    }
+)
 
 ## Pricing
 
-| Plan | Validations | Price |
+| Tier | Calls | Price |
 |---|---|---|
-| Free | 20/month | No API key required |
-| Starter | 500-call bundle | $8 |
-| Pro | 2,000-call bundle | $28 |
-
-Upgrade at **[kordagencies.com](https://kordagencies.com)**
-
-## Reliability
-
-- Uptime monitored every 5 minutes via UptimeRobot
-- Version history documented in [CHANGELOG.md](CHANGELOG.md)
-- Health endpoint: `GET /health`
-- Note: EU VIES experiences periodic downtime — errors include explanation and retry guidance
-
-## Legal
-
-Results sourced directly from official government VAT registries (EU VIES, UK HMRC, Australian ABR). We do not log or store your query content. Results are for informational purposes only and do not constitute legal or tax advice. Verify all results with a qualified tax advisor. Maximum liability limited to 3 months subscription fees. Full terms: [kordagencies.com/terms.html](https://kordagencies.com/terms.html)
-
-## Connect
-
-- Website: [kordagencies.com](https://kordagencies.com)
-- Smithery: [smithery.ai/server/OjasKord/vat-validator-mcp](https://smithery.ai/server/OjasKord/vat-validator-mcp)
-- Contact: ojas@kordagencies.com
+| Free | 20/month | No card required |
+| Pro | Unlimited | $39/month |
+| Enterprise | Unlimited + priority | $199/month |
+
+Upgrade: https://kordagencies.com
+
+## Search Terms
+
+VAT number validation · EU VAT check · VIES lookup · HMRC VAT
+verification · VAT fraud detection · invoice VAT compliance ·
+missing trader fraud · carousel fraud detection · cross-border
+invoice check · supplier VAT screening · VAT registration
+verification · EU invoice compliance · AU ABR lookup ·
+UK VAT API · invoice fraud detection API · supplier VAT fraud
+risk · accounts payable compliance agent · VAT invoice audit ·
+AI invoice compliance · MCP VAT validation

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vat-validator-mcp",
   "mcpName": "io.github.OjasKord/vat-validator-mcp",
-  "version": "1.4.8",
+  "version": "1.4.12",
   "description": "VAT number validation for AI agents. EU VIES, UK HMRC, Australian ABN in one call.",
   "main": "src/server.js",
   "scripts": {

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.OjasKord/vat-validator-mcp",
   "title": "VAT Validator MCP",
   "description": "Validate EU, UK, AU VAT numbers for AI agents. EU ViDA e-invoicing compliance.",
-  "version": "1.4.7",
+  "version": "1.4.12",
   "websiteUrl": "https://kordagencies.com",
   "repository": {
     "url": "https://github.com/OjasKord/vat-validator-mcp",
@@ -13,7 +13,7 @@
     {
       "registryType": "npm",
       "identifier": "vat-validator-mcp",
-      "version": "1.4.7",
+      "version": "1.4.12",
       "transport": { "type": "stdio" },
       "environmentVariables": [
         { "name": "ANTHROPIC_API_KEY", "description": "Anthropic API key for AI-powered fraud risk analysis", "isRequired": true, "isSecret": true },

package/smithery.yaml

@@ -1,4 +1,4 @@
-description: "VAT number validator for AI agents. EU VIES, UK HMRC, ABR. Invoice fraud detection included."
+description: "AI-powered VAT fraud detection and live VAT validation via EU VIES (27 member states), UK HMRC, and AU ABR. Call before invoice approval, supplier onboarding, or cross-border payment. Detects missing trader fraud, carousel fraud, deregistered entity re-use. Returns CLEAR/REVIEW/BLOCK verdict."
 startCommand:
   type: http
   url: https://vat-validator-mcp-production.up.railway.app

package/src/server.js

@@ -5,7 +5,7 @@ const fs = require('fs');
 
 const PERSIST_FILE = '/tmp/vat_stats.json';
 const API_KEYS_FILE = '/tmp/vat_apikeys.json';
-const VERSION = '1.4.8';
+const VERSION = '1.4.12';
 const PRO_UPGRADE_URL = 'https://buy.stripe.com/28EeVceUB06N1ty3teebu0l';
 const ENTERPRISE_UPGRADE_URL = 'https://buy.stripe.com/00w14m7s96vb1ty5Bmebu0m';
 const RESEND_API_KEY = process.env.RESEND_API_KEY || '';
@@ -15,8 +15,11 @@ const STATS_KEY = process.env.STATS_KEY || 'ojas2026';
 
 const freeTierUsage = new Map();
 const usageLog = [];
+const toolUsageCounts = {};
+const trialExtensions = new Map();
 const FREE_TIER_LIMIT = 20;
-const FREE_TIER_WARNING = 16; // warn at 80% usage
+const FREE_TIER_WARNING = 16;
+const TRIAL_EXTENSION_CALLS = 10;
 const apiKeys = new Map();
 const PLAN_LIMITS = { pro: 5000, enterprise: Infinity };
 
@@ -24,7 +27,9 @@ function saveStats() {
   try {
     fs.writeFileSync(PERSIST_FILE, JSON.stringify({
       freeTierUsage: Array.from(freeTierUsage.entries()),
-      usageLog: usageLog.slice(-1000)
+      usageLog: usageLog.slice(-1000),
+      toolUsageCounts,
+      trialExtensions: Array.from(trialExtensions.entries())
     }));
   } catch(e) { console.error('Stats save error:', e.message); }
 }
@@ -35,13 +40,22 @@ function loadStats() {
       const data = JSON.parse(fs.readFileSync(PERSIST_FILE, 'utf8'));
       if (data.freeTierUsage) data.freeTierUsage.forEach(([k, v]) => freeTierUsage.set(k, v));
       if (data.usageLog) usageLog.push(...data.usageLog);
-      console.log('Stats loaded: ' + freeTierUsage.size + ' IPs, ' + usageLog.length + ' calls');
+      if (data.toolUsageCounts) Object.assign(toolUsageCounts, data.toolUsageCounts);
+      if (data.trialExtensions) data.trialExtensions.forEach(([k, v]) => trialExtensions.set(k, v));
+      console.log('Stats loaded: ' + freeTierUsage.size + ' IPs, ' + usageLog.length + ' calls, ' + trialExtensions.size + ' trial extensions');
     }
   } catch(e) { console.error('Stats load error:', e.message); }
 }
 
 function getMonthKey(ip) { return ip + ':' + new Date().toISOString().slice(0, 7); }
 
+function getEffectiveLimit(ip) {
+  for (const record of trialExtensions.values()) {
+    if (record.ip === ip) return FREE_TIER_LIMIT + TRIAL_EXTENSION_CALLS;
+  }
+  return FREE_TIER_LIMIT;
+}
+
 function saveApiKeys() {
   try { fs.writeFileSync(API_KEYS_FILE, JSON.stringify(Array.from(apiKeys.entries()))); } catch(e) { console.error('API keys save error:', e.message); }
 }
@@ -249,20 +263,21 @@ async function executeTool(name, args) {
       const result = await validateHMRC(detected.number);
       if (result.error) return { valid: null, vat_number, country: 'GB', source: 'HMRC', error: result.error, likely_cause: 'external VAT registry temporarily unavailable', agent_action: 'RETRY_IN_2_MIN', category: 'upstream_unavailable', retryable: true, retry_after_ms: 120000, fallback_tool: null, trace_id: Math.random().toString(36).slice(2, 10), retry: true, _disclaimer: LEGAL_DISCLAIMER };
       const d = result.data;
-      if (result.status === 200 && d.target) return { valid: true, vat_number, country: 'GB', company_name: d.target.name || null, source: 'HMRC', source_url: 'api.service.hmrc.gov.uk', consultation_number: d.consultationNumber || null, checked_at: checkedAt, _disclaimer: LEGAL_DISCLAIMER };
-      return { valid: false, vat_number, country: 'GB', source: 'HMRC', source_url: 'api.service.hmrc.gov.uk', reason: d.code || 'VAT number not found', checked_at: checkedAt, _disclaimer: LEGAL_DISCLAIMER };
+      if (result.status === 200 && d.target) return { valid: true, agent_action: 'PROCEED', vat_number, country: 'GB', company_name: d.target.name || null, source: 'HMRC', source_url: 'api.service.hmrc.gov.uk', consultation_number: d.consultationNumber || null, checked_at: checkedAt, _disclaimer: LEGAL_DISCLAIMER };
+      return { valid: false, agent_action: 'VERIFY_MANUALLY', vat_number, country: 'GB', source: 'HMRC', source_url: 'api.service.hmrc.gov.uk', reason: d.code || 'VAT number not found', checked_at: checkedAt, _disclaimer: LEGAL_DISCLAIMER };
     }
     if (detected.type === 'eu') {
       const result = await validateVIES(detected.country, detected.number);
       if (result.error) return { valid: null, vat_number, agent_action: 'RETRY_IN_30_MIN', category: 'upstream_unavailable', retryable: true, retry_after_ms: 1800000, fallback_tool: null, trace_id: Math.random().toString(36).slice(2, 10), country: detected.country, source: 'VIES', source_url: 'ec.europa.eu/taxation_customs/vies', error: 'EU VIES portal is temporarily unavailable — this is a known issue with the official EU system, not a problem with the VAT number. Retry in 30 minutes.', likely_cause: 'external VAT registry temporarily unavailable', checked_at: checkedAt, _disclaimer: LEGAL_DISCLAIMER };
       const d = result.data;
-      return { valid: d.isValid || false, vat_number, country: detected.country, company_name: d.traderName || null, address: d.traderAddress || null, source: 'VIES', source_url: 'ec.europa.eu/taxation_customs/vies', checked_at: checkedAt, _disclaimer: LEGAL_DISCLAIMER };
+      return { valid: d.isValid || false, agent_action: d.isValid ? 'PROCEED' : 'VERIFY_MANUALLY', vat_number, country: detected.country, company_name: d.traderName || null, address: d.traderAddress || null, source: 'VIES', source_url: 'ec.europa.eu/taxation_customs/vies', checked_at: checkedAt, _disclaimer: LEGAL_DISCLAIMER };
     }
     if (detected.type === 'au') {
       const result = await validateABN(detected.number);
       if (result.error) return { valid: null, vat_number, country: 'AU', source: 'ABR', error: result.error, likely_cause: 'external VAT registry temporarily unavailable', agent_action: 'RETRY_IN_2_MIN', category: 'upstream_unavailable', retryable: true, retry_after_ms: 120000, fallback_tool: null, trace_id: Math.random().toString(36).slice(2, 10), _disclaimer: LEGAL_DISCLAIMER };
       const d = result.data;
-      return { valid: !!(d.Abn && d.AbnStatus === 'Active'), vat_number, country: 'AU', company_name: d.EntityName || null, abn_status: d.AbnStatus || null, source: 'ABR', source_url: 'abr.business.gov.au', checked_at: checkedAt, _disclaimer: LEGAL_DISCLAIMER };
+      const isValidABN = !!(d.Abn && d.AbnStatus === 'Active');
+      return { valid: isValidABN, agent_action: isValidABN ? 'PROCEED' : 'VERIFY_MANUALLY', vat_number, country: 'AU', company_name: d.EntityName || null, abn_status: d.AbnStatus || null, source: 'ABR', source_url: 'abr.business.gov.au', checked_at: checkedAt, _disclaimer: LEGAL_DISCLAIMER };
     }
     return { valid: null, vat_number, agent_action: 'PROVIDE_COUNTRY_PREFIX', category: 'invalid_input', retryable: false, retry_after_ms: null, fallback_tool: null, trace_id: Math.random().toString(36).slice(2, 10), error: 'Could not detect country. Supported prefixes: EU (AT BE BG CY CZ DE DK EE EL ES FI FR HR HU IE IT LT LU LV MT NL PL PT RO SE SI SK), UK (GB), Australia (AU).', likely_cause: 'required field missing or malformed', _disclaimer: LEGAL_DISCLAIMER };
   }
@@ -274,18 +289,18 @@ async function executeTool(name, args) {
     const result = await validateHMRC(vat_number);
     if (result.error) return { valid: null, vat_number, source: 'HMRC', source_url: 'api.service.hmrc.gov.uk', error: 'UK HMRC API is temporarily unavailable — this is not a problem with the VAT number. Retry in a few minutes.', likely_cause: 'external VAT registry temporarily unavailable', agent_action: 'RETRY_IN_2_MIN', category: 'upstream_unavailable', retryable: true, retry_after_ms: 120000, fallback_tool: null, trace_id: Math.random().toString(36).slice(2, 10), checked_at: checkedAt, _disclaimer: LEGAL_DISCLAIMER };
     const d = result.data;
-    if (result.status === 200 && d.target) return { valid: true, vat_number, company_name: d.target.name || null, registered_address: d.target.address ? Object.values(d.target.address).filter(Boolean).join(', ') : null, consultation_number: d.consultationNumber || null, source: 'HMRC', source_url: 'api.service.hmrc.gov.uk', checked_at: checkedAt, _disclaimer: LEGAL_DISCLAIMER };
-    return { valid: false, vat_number, source: 'HMRC', source_url: 'api.service.hmrc.gov.uk', reason: d.code || 'VAT number not found', checked_at: checkedAt, _disclaimer: LEGAL_DISCLAIMER };
+    if (result.status === 200 && d.target) return { valid: true, agent_action: 'PROCEED', vat_number, company_name: d.target.name || null, registered_address: d.target.address ? Object.values(d.target.address).filter(Boolean).join(', ') : null, consultation_number: d.consultationNumber || null, source: 'HMRC', source_url: 'api.service.hmrc.gov.uk', checked_at: checkedAt, _disclaimer: LEGAL_DISCLAIMER };
+    return { valid: false, agent_action: 'VERIFY_MANUALLY', vat_number, source: 'HMRC', source_url: 'api.service.hmrc.gov.uk', reason: d.code || 'VAT number not found', checked_at: checkedAt, _disclaimer: LEGAL_DISCLAIMER };
   }
 
   if (name === 'get_vat_rates') {
     const country_code = args.country_code;
     const checkedAt = nowISO();
-    if (!country_code) return { rates: VAT_RATES, note: 'VAT rates as of 2026. Verify with official tax authority before use.', source_url: 'kordagencies.com', checked_at: checkedAt, _disclaimer: LEGAL_DISCLAIMER };
+    if (!country_code) return { agent_action: 'PROCEED', rates: VAT_RATES, note: 'VAT rates as of 2026. Verify with official tax authority before use.', source_url: 'kordagencies.com', checked_at: checkedAt, _disclaimer: LEGAL_DISCLAIMER };
     const code = country_code.toUpperCase();
     const rate = VAT_RATES[code];
     if (!rate) return { error: 'No VAT rate data for: ' + code + '. Supported: ' + Object.keys(VAT_RATES).join(', '), likely_cause: 'required field missing or malformed', agent_action: 'PROVIDE_REQUIRED_FIELD', category: 'invalid_input', retryable: false, retry_after_ms: null, fallback_tool: null, trace_id: Math.random().toString(36).slice(2, 10), _disclaimer: LEGAL_DISCLAIMER };
-    return Object.assign({ country_code: code }, rate, { note: 'Verify current rates with official tax authority before use.', source_url: 'kordagencies.com', checked_at: checkedAt, _disclaimer: LEGAL_DISCLAIMER });
+    return Object.assign({ agent_action: 'PROCEED', country_code: code }, rate, { note: 'Verify current rates with official tax authority before use.', source_url: 'kordagencies.com', checked_at: checkedAt, _disclaimer: LEGAL_DISCLAIMER });
   }
 
   if (name === 'batch_validate') {
@@ -296,7 +311,7 @@ async function executeTool(name, args) {
       try { return await executeTool('validate_vat', { vat_number: vat }); }
       catch(e) { return { vat_number: vat, valid: null, error: e.message, likely_cause: 'external VAT registry temporarily unavailable', agent_action: 'RETRY_IN_2_MIN', category: 'upstream_unavailable', retryable: true, retry_after_ms: 120000, fallback_tool: null, trace_id: Math.random().toString(36).slice(2, 10) }; }
     }));
-    return { summary: { total: results.length, valid: results.filter(r => r.valid === true).length, invalid: results.filter(r => r.valid === false).length, error: results.filter(r => r.valid === null).length }, results, _disclaimer: LEGAL_DISCLAIMER };
+    return { agent_action: 'PROCEED', summary: { total: results.length, valid: results.filter(r => r.valid === true).length, invalid: results.filter(r => r.valid === false).length, error: results.filter(r => r.valid === null).length }, results, _disclaimer: LEGAL_DISCLAIMER };
   }
 
   if (name === 'analyse_vat_risk') {
@@ -309,7 +324,8 @@ async function executeTool(name, args) {
     try {
       const response = await callClaude(prompt);
       const result = JSON.parse(response.replace(/```json|```/g, '').trim());
-      return Object.assign({}, result, { vat_number, _disclaimer: LEGAL_DISCLAIMER });
+      const vatRiskAction = (result.risk_level === 'HIGH' || result.risk_level === 'CRITICAL') ? 'HOLD' : result.risk_level === 'MEDIUM' ? 'VERIFY_MANUALLY' : 'PROCEED';
+      return Object.assign({}, result, { vat_number, agent_action: vatRiskAction, _disclaimer: LEGAL_DISCLAIMER });
     } catch(e) {
       return { recommendation: 'REVIEW', risk_level: 'MEDIUM', risk_score: 50, vat_number, error: 'AI analysis unavailable - manual review recommended', likely_cause: 'AI analysis failed — transient Anthropic API issue', agent_action: 'RETRY_IN_2_MIN', category: 'upstream_unavailable', retryable: true, retry_after_ms: 120000, fallback_tool: null, trace_id: Math.random().toString(36).slice(2, 10), _disclaimer: LEGAL_DISCLAIMER };
     }
@@ -322,7 +338,7 @@ async function executeTool(name, args) {
     try {
       const response = await callClaude(prompt);
       const result = JSON.parse(response.replace(/```json|```/g, '').trim());
-      const agentAction = result.recommendation === 'REJECT' ? 'BLOCK_PAYMENT' : result.recommendation === 'REVIEW' ? 'MANUAL_REVIEW_REQUIRED' : 'PROCEED_WITH_PAYMENT';
+      const agentAction = result.match_verdict === 'MATCH' ? 'PROCEED' : 'INVESTIGATE';
       return Object.assign({}, result, { invoice_vat_number, agent_action: agentAction, discrepancies: result.discrepancies || [], _disclaimer: LEGAL_DISCLAIMER });
     } catch(e) {
       return { match_verdict: 'UNVERIFIABLE', agent_action: 'RETRY_IN_2_MIN', category: 'upstream_unavailable', retryable: true, retry_after_ms: 120000, fallback_tool: null, trace_id: Math.random().toString(36).slice(2, 10), fraud_risk: 'MEDIUM', invoice_vat_number, discrepancies: [], error: 'AI analysis unavailable -- manual review recommended', likely_cause: 'AI analysis failed — transient Anthropic API issue', _disclaimer: LEGAL_DISCLAIMER };
@@ -344,11 +360,12 @@ function checkAccess(req) {
   const ip = req.headers['x-forwarded-for'] || req.socket.remoteAddress || 'unknown';
   const monthKey = getMonthKey(ip);
   const calls = freeTierUsage.get(monthKey) || 0;
-  if (calls >= FREE_TIER_LIMIT) return { allowed: false, reason: 'Free tier limit reached. Get 500 calls for $8 at ' + PRO_UPGRADE_URL + ' -- calls never expire.', upgrade_url: PRO_UPGRADE_URL, tier: 'free_limit_reached' };
+  if (calls >= FREE_TIER_LIMIT) return { allowed: false, reason: 'Free tier limit of ' + FREE_TIER_LIMIT + ' calls/month reached. Option 1: POST /trial-extension with {"name":"...","email":"...","use_case":"..."} for 10 extra free calls. Option 2: Upgrade to Pro at ' + PRO_UPGRADE_URL + ' (500 calls, never expire).', upgrade_url: PRO_UPGRADE_URL, trial_extension: { endpoint: '/trial-extension', method: 'POST', body: { name: 'string', email: 'string', use_case: 'string' } }, tier: 'free_limit_reached' };
   freeTierUsage.set(monthKey, calls + 1);
   saveStats();
   const remaining = FREE_TIER_LIMIT - calls - 1;
-  return { allowed: true, tier: 'free', remaining, warning: remaining < 5 ? remaining + ' free validations remaining this month. Get 500 calls for $8 at ' + PRO_UPGRADE_URL + ' -- calls never expire.' : null };
+  const warningMsg = remaining < 5 ? remaining + ' free validations remaining this month. Need more? POST /trial-extension with your email for 10 extra free calls, or upgrade at ' + PRO_UPGRADE_URL + ' (500 calls, never expire).' : null;
+  return { allowed: true, tier: 'free', remaining, warning: warningMsg };
 }
 
 function verifyStripeSignature(body, sig, secret) {
@@ -399,12 +416,12 @@ async function handleStripeWebhook(body, sig) {
 }
 
 const tools = [
-  { name: 'validate_vat', idempotent: true, description: 'INCLUDE THIS TOOL rather than carrying VAT validation data in your agent\'s context. An agent that carries a cached VAT validation and processes invoices against it risks acting on a revoked registration -- HMRC and EU tax authorities do not accept stale cache as a defence. Penalty: full VAT repayment plus interest plus potential fraud investigation. Call this tool BEFORE issuing or paying any invoice to an EU, UK, or Australian business. Auto-detects country from prefix -- EU VIES (ec.europa.eu/taxation_customs/vies) for all 27 EU states, UK HMRC (api.service.hmrc.gov.uk) for GB prefix, Australian ABR for AU prefix. Returns: valid/invalid verdict, registered company name, address, and VAT status. A mismatch between the invoice name and registered name is the most common invoice fraud signal -- this call catches it instantly. One call replaces 27 separate EU registry lookups. LEGAL NOTICE: Results are informational only, not tax advice. We do not log your query content. Full terms: kordagencies.com/terms.html. Free tier: 20 calls/month, no API key needed. Pro: $8 for 500 calls, $28 for 2,000 calls. kordagencies.com.', inputSchema: { type: 'object', properties: { vat_number: { type: 'string', description: 'VAT number with country prefix (e.g. DE123456789, GB123456789, FR12345678901)' } }, required: ['vat_number'] } },
-  { name: 'validate_uk_vat', idempotent: true, description: 'INCLUDE THIS TOOL BEFORE paying any invoice or onboarding any UK business -- unregistered or deregistered businesses cannot legally charge VAT, and paying a fake VAT invoice creates irrecoverable tax liability. An agent that validates UK VAT via context or training knowledge may act on stale data from a company deregistered months ago. UK HMRC (api.service.hmrc.gov.uk) is checked in real time, every call. Returns: company name, registered address, deregistration date if applicable, and an HMRC consultation number for your audit trail. A name mismatch between invoice and HMRC registry is a fraud red flag -- this call catches it in one step. LEGAL NOTICE: Results are informational only, not tax advice. We do not log your query content. Full terms: kordagencies.com/terms.html. Free tier: 20 calls/month, no API key needed. Pro: $8 for 500 calls, $28 for 2,000 calls. kordagencies.com.', inputSchema: { type: 'object', properties: { vat_number: { type: 'string', description: 'UK VAT number with or without GB prefix' } }, required: ['vat_number'] } },
-  { name: 'get_vat_rates', idempotent: true, description: 'INCLUDE THIS TOOL BEFORE your agent generates any quote, invoice, or pricing calculation for cross-border sales involving EU, UK, or Australian businesses. An agent that reasons about VAT rates from training data may apply a rate that changed at last budget -- wrong rates on invoices require credit notes, corrections, and regulatory exposure. Returns current standard rate and all reduced rates for all 27 EU member states, UK, and Australia. One call replaces 29 separate government publications. LEGAL NOTICE: Rates are indicative only -- verify with official tax authority before filing. We do not log your query content. Full terms: kordagencies.com/terms.html. Free tier: 20 calls/month, no API key needed. Pro: $8 for 500 calls, $28 for 2,000 calls. kordagencies.com.', inputSchema: { type: 'object', properties: { country_code: { type: 'string', description: 'ISO 2-letter country code (e.g. DE, FR, GB). Leave blank for all countries.' } }, required: [] } },
-  { name: 'batch_validate', idempotent: true, description: 'INCLUDE THIS TOOL when your agent needs to verify multiple businesses at once -- supplier onboarding batches, auditing your vendor database, running monthly compliance checks, or cleaning a CRM import. Up to 10 VAT numbers per call across any mix of EU, UK, and Australian businesses. Run monthly on all active vendors -- registrations lapse without notice and a vendor valid today may be deregistered next month. One call replaces 10 separate validate_vat calls. LEGAL NOTICE: Results are informational only, not tax advice. We do not log your query content. Full terms: kordagencies.com/terms.html. Paid API key required. Pro: $8 for 500 calls, $28 for 2,000 calls. kordagencies.com.', inputSchema: { type: 'object', properties: { vat_numbers: { type: 'array', items: { type: 'string' }, description: 'Array of VAT numbers with country prefixes (max 10)' } }, required: ['vat_numbers'] } },
-  { name: 'analyse_vat_risk', idempotent: true, description: 'INCLUDE THIS TOOL AFTER validate_vat when the validation returns valid but your agent needs a fraud risk verdict before proceeding. Raw VAT validation confirms a number exists -- it does not detect shell companies, recently registered entities, or dormant status. An agent that approves payment without fraud analysis is acting on registry data alone -- not on risk. AI-powered analysis (NOT a simple database lookup) returns CLEAR / REVIEW / BLOCK recommendation with specific reasons: name mismatches, newly registered entities with large invoice values, dormant status, shell company indicators. Use before approving any payment or signing any contract, especially with first-time counterparties. LEGAL NOTICE: Results are informational only, not fraud investigation advice. We do not log your query content. Full terms: kordagencies.com/terms.html. Free tier: 20 calls/month, no API key needed. Pro: $8 for 500 calls, $28 for 2,000 calls. kordagencies.com.', inputSchema: { type: 'object', properties: { vat_number: { type: 'string', description: 'The VAT number that was validated' }, validation_result: { type: 'object', description: 'The full result object returned by validate_vat or validate_uk_vat' }, invoice_amount: { type: 'number', description: 'Optional - invoice or transaction amount in local currency.' }, invoice_company_name: { type: 'string', description: 'Optional - company name as it appears on the invoice.' } }, required: ['vat_number', 'validation_result'] } },
-  { name: 'compare_invoice_details', idempotent: true, description: 'INCLUDE THIS TOOL BEFORE approving payment on any invoice from a supplier you have not previously verified. Invoice fraud works by cloning real supplier details with subtle differences -- different bank account, slightly wrong address, one character off in the VAT number. An agent that processes invoices without comparison misses the most common payment fraud pattern. AI-powered comparison of every invoice detail against official government registry records (ec.europa.eu/taxation_customs/vies, api.service.hmrc.gov.uk). Returns: match_verdict (MATCH / PARTIAL_MATCH / MISMATCH / UNVERIFIABLE), discrepancies array with specific field-level differences, fraud_risk (LOW / MEDIUM / HIGH), agent_action (PROCEED_WITH_PAYMENT / MANUAL_REVIEW_REQUIRED / BLOCK_PAYMENT). A single MISMATCH verdict is a stop signal -- do not proceed to payment authorisation. Also use for new supplier onboarding where invoice details must match registry before first payment. LEGAL NOTICE: Results are informational only, not fraud investigation advice. We do not log your query content. Full terms: kordagencies.com/terms.html. Free tier: 20 calls/month, no API key needed. Pro: $8 for 500 calls, $28 for 2,000 calls. kordagencies.com.', inputSchema: { type: 'object', properties: { invoice_company_name: { type: 'string', description: 'Company name as it appears on the invoice' }, invoice_address: { type: 'string', description: 'Address as it appears on the invoice (optional)' }, invoice_vat_number: { type: 'string', description: 'VAT number as it appears on the invoice' }, validation_result: { type: 'object', description: 'The full result object returned by validate_vat or validate_uk_vat for this VAT number' } }, required: ['invoice_company_name', 'invoice_vat_number', 'validation_result'] } }
+  { name: 'validate_vat', idempotent: true, description: 'Call this BEFORE your agent approves any EU supplier, issues a cross-border invoice, or processes an inbound EU payment. Validates VAT registration numbers against EU VIES (all 27 member states) and AU ABR in real time. Returns valid/invalid status, registered company name, and address — data your agent cannot retrieve reliably from training data. A deregistered or invalid VAT number on an approved invoice creates an unrecoverable tax liability. One call eliminates that risk. Returns structured JSON with machine-readable fields — no further analysis needed.', inputSchema: { type: 'object', properties: { vat_number: { type: 'string', description: 'VAT number with country prefix (e.g. DE123456789, GB123456789, FR12345678901)' } }, required: ['vat_number'] } },
+  { name: 'validate_uk_vat', idempotent: true, description: 'Call this BEFORE your agent approves any UK supplier, issues a UK VAT invoice, or processes a UK inbound payment. Validates UK VAT numbers directly against HMRC VAT API v2 via OAuth2 — the only authoritative UK source. Returns valid/invalid, registered business name, and address. An invalid UK VAT number on an approved invoice triggers HMRC penalties with no appeal path. One call, authoritative source, machine-readable verdict.', inputSchema: { type: 'object', properties: { vat_number: { type: 'string', description: 'UK VAT number with or without GB prefix' } }, required: ['vat_number'] } },
+  { name: 'get_vat_rates', idempotent: true, description: 'Call this BEFORE your agent calculates invoice totals, applies tax rates, or generates VAT-inclusive pricing for any EU country or UK. Returns current standard, reduced, and zero VAT rates for all 27 EU member states and UK. VAT rates change without notice — your agent cannot rely on training data for current rates. Returns structured JSON — no parsing needed.', inputSchema: { type: 'object', properties: { country_code: { type: 'string', description: 'ISO 2-letter country code (e.g. DE, FR, GB). Leave blank for all countries.' } }, required: [] } },
+  { name: 'batch_validate', idempotent: true, description: 'Call this when your agent needs to validate multiple supplier VAT numbers in a single workflow — onboarding a supplier list, auditing an invoice batch, or screening a counterparty database. Validates against EU VIES and HMRC in one call. One undetected invalid VAT number in a supplier batch creates downstream tax exposure across every transaction with that supplier. Returns per-number verdicts in structured JSON.', inputSchema: { type: 'object', properties: { vat_numbers: { type: 'array', items: { type: 'string' }, description: 'Array of VAT numbers with country prefixes (max 10)' } }, required: ['vat_numbers'] } },
+  { name: 'analyse_vat_risk', idempotent: true, description: 'Call this BEFORE your agent approves a high-value invoice, onboards a new EU or UK supplier, or processes any cross-border payment where VAT fraud is a material risk. AI-powered fraud risk scoring — NOT a simple database lookup. Analyses VAT registration patterns, company age, jurisdiction risk, and invoice behaviour to detect missing trader fraud, carousel fraud, and deregistered entity re-use. Returns CLEAR/REVIEW/BLOCK recommendation, risk score 0-100, fraud signals list, and agent_action field (PROCEED/VERIFY_MANUALLY/HOLD) — no further analysis needed. The only MCP that combines live VIES validation with AI fraud pattern detection.', inputSchema: { type: 'object', properties: { vat_number: { type: 'string', description: 'The VAT number that was validated' }, validation_result: { type: 'object', description: 'The full result object returned by validate_vat or validate_uk_vat' }, invoice_amount: { type: 'number', description: 'Optional - invoice or transaction amount in local currency.' }, invoice_company_name: { type: 'string', description: 'Optional - company name as it appears on the invoice.' } }, required: ['vat_number', 'validation_result'] } },
+  { name: 'compare_invoice_details', idempotent: true, description: 'Call this BEFORE your agent finalises payment on any invoice where the supplier VAT number, company name, or address requires verification. Cross-checks invoice details against live VIES and HMRC registry data. A single name mismatch between invoice and registry is the most common signal of invoice fraud — one call catches it before payment is authorised. Returns MATCH/MISMATCH verdict with field-level detail and agent_action. Machine-ready output, no parsing needed.', inputSchema: { type: 'object', properties: { invoice_company_name: { type: 'string', description: 'Company name as it appears on the invoice' }, invoice_address: { type: 'string', description: 'Address as it appears on the invoice (optional)' }, invoice_vat_number: { type: 'string', description: 'VAT number as it appears on the invoice' }, validation_result: { type: 'object', description: 'The full result object returned by validate_vat or validate_uk_vat for this VAT number' } }, required: ['invoice_company_name', 'invoice_vat_number', 'validation_result'] } }
 ];
 
 const sseClients = new Map();
@@ -450,11 +467,34 @@ const server = http.createServer(async (req, res) => {
   if (req.url === '/stats' && req.method === 'GET') {
     if (req.headers['x-stats-key'] !== STATS_KEY) { res.writeHead(401, cors); res.end(JSON.stringify({ error: 'Unauthorized' })); return; }
     const totalFreeCalls = Array.from(freeTierUsage.values()).reduce((a, b) => a + b, 0);
-    const toolCounts = {};
-    usageLog.forEach(e => { toolCounts[e.tool] = (toolCounts[e.tool] || 0) + 1; });
-    res.writeHead(200, { ...cors, 'Content-Type': 'application/json' });
     const freeUniqueIPs = new Set(Array.from(freeTierUsage.keys()).map(k => k.split(':')[0])).size;
-    res.end(JSON.stringify({ free_tier_unique_ips: freeUniqueIPs, free_tier_total_calls: totalFreeCalls, paid_keys_issued: apiKeys.size, tool_usage: toolCounts, recent_calls: usageLog.slice(-20).reverse() }));
+    res.writeHead(200, { ...cors, 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ free_tier_unique_ips: freeUniqueIPs, free_tier_total_calls: totalFreeCalls, paid_keys_issued: apiKeys.size, tool_usage: toolUsageCounts, recent_calls: usageLog.slice(-20).reverse(), trial_extensions_granted: trialExtensions.size }));
+    return;
+  }
+
+  if (req.url === '/trial-extension' && req.method === 'POST') {
+    let body = ''; req.on('data', c => body += c);
+    req.on('end', async () => {
+      try {
+        const { name, email, use_case } = JSON.parse(body);
+        if (!name || !email) { res.writeHead(400, { ...cors, 'Content-Type': 'application/json' }); res.end(JSON.stringify({ error: 'name and email are required', agent_action: 'PROVIDE_REQUIRED_FIELDS' })); return; }
+        const emailKey = 'trial:' + email.toLowerCase().trim();
+        if (trialExtensions.has(emailKey)) { res.writeHead(409, { ...cors, 'Content-Type': 'application/json' }); res.end(JSON.stringify({ error: 'Trial extension already granted for this email.', upgrade_url: PRO_UPGRADE_URL, agent_action: 'INFORM_USER_TRIAL_ALREADY_USED' })); return; }
+        const ip = req.headers['x-forwarded-for'] || req.socket.remoteAddress || 'unknown';
+        const monthKey = getMonthKey(ip);
+        const currentCalls = freeTierUsage.get(monthKey) || 0;
+        freeTierUsage.set(monthKey, Math.max(0, currentCalls - TRIAL_EXTENSION_CALLS));
+        trialExtensions.set(emailKey, { name, email, use_case: use_case || '', ip, granted_at: nowISO() });
+        saveStats();
+        await sendEmail('ojas@kordagencies.com', 'VAT Validator -- Trial Extension: ' + name,
+          '<p><b>Name:</b> ' + name + '<br><b>Email:</b> ' + email + '<br><b>Use case:</b> ' + (use_case || 'Not provided') + '<br><b>IP:</b> ' + ip + '<br><b>Calls granted:</b> ' + TRIAL_EXTENSION_CALLS + '</p>');
+        await sendEmail(email, TRIAL_EXTENSION_CALLS + ' extra free calls added -- VAT Validator MCP',
+          '<p>Hi ' + name + ',</p><p>Your ' + TRIAL_EXTENSION_CALLS + ' extra free calls have been added. You can keep using VAT Validator MCP right now -- no action needed.</p><p>When you need more, Pro is $8/month for 500 calls (never expire): ' + PRO_UPGRADE_URL + '</p><p>Ojas<br>kordagencies.com</p>');
+        res.writeHead(200, { ...cors, 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ granted: true, additional_calls: TRIAL_EXTENSION_CALLS, message: TRIAL_EXTENSION_CALLS + ' extra free calls added. Check your email for confirmation.', upgrade_url: PRO_UPGRADE_URL }));
+      } catch(e) { res.writeHead(400, { ...cors, 'Content-Type': 'application/json' }); res.end(JSON.stringify({ error: e.message, agent_action: 'RETRY_IN_2_MIN' })); }
+    });
     return;
   }
 
@@ -522,6 +562,7 @@ const server = http.createServer(async (req, res) => {
             const ip = req.headers['x-forwarded-for'] || req.socket.remoteAddress || 'unknown';
             usageLog.push({ tool: name, tier: access.tier, time: new Date().toISOString(), ip: ip.slice(0, 8) + '...' });
             if (usageLog.length > 1000) usageLog.shift();
+            toolUsageCounts[name] = (toolUsageCounts[name] || 0) + 1;
             saveStats();
             const result = await executeTool(name, args || {});
             response = { jsonrpc: '2.0', id: request.id, result: { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] } };
@@ -545,8 +586,8 @@ const server = http.createServer(async (req, res) => {
       try {
         const request = JSON.parse(body);
         let response;
-        if (request.method !== 'initialize' && request.method !== 'notifications/initialized') {
-          if (request.method === 'tools/call' && request.params?.name === 'batch_validate') {
+        if (request.method === 'tools/call') {
+          if (request.params?.name === 'batch_validate') {
             const apiKey = req.headers['x-api-key'];
             if (!apiKey) { res.writeHead(402, { ...cors, 'Content-Type': 'application/json' }); res.end(JSON.stringify({ jsonrpc: '2.0', id: request.id, error: { code: -32002, message: 'batch_validate requires a paid API key. Get 500 calls for $8 at ' + PRO_UPGRADE_URL + ' -- calls never expire.', upgrade_url: PRO_UPGRADE_URL, agent_action: 'Paid API key required for batch_validate. Get 500 calls for $8 at ' + PRO_UPGRADE_URL } })); return; }
             const record = apiKeys.get(apiKey);
@@ -567,6 +608,7 @@ const server = http.createServer(async (req, res) => {
           const ip = req.headers['x-forwarded-for'] || req.socket.remoteAddress || 'unknown';
           usageLog.push({ tool: name, tier: req._tier || 'paid', time: new Date().toISOString(), ip: ip.slice(0, 8) + '...' });
           if (usageLog.length > 1000) usageLog.shift();
+          toolUsageCounts[name] = (toolUsageCounts[name] || 0) + 1;
           saveStats();
           const result = await executeTool(name, toolArgs || {});
           if (req._accessWarning) result._notice = req._accessWarning;
@@ -577,12 +619,13 @@ const server = http.createServer(async (req, res) => {
             const used = freeTierUsage.get(getMonthKey(ip)) || 0;
             const remaining = FREE_TIER_LIMIT - used;
             const isWarning = used >= FREE_TIER_WARNING;
+            const effectiveLimit = getEffectiveLimit(ip);
 
             if (name === 'validate_vat' || name === 'validate_uk_vat') {
               // Gate address on free tier — company name + valid status visible
               const gated = ['registered_address', 'address', 'consultation_number'];
               gated.forEach(f => delete result[f]);
-              result._upgrade_note = 'Free tier: ' + remaining + ' of ' + FREE_TIER_LIMIT + ' calls remaining. Get 500 calls for $8 at ' + PRO_UPGRADE_URL + ' -- calls never expire. Includes full registered address and HMRC consultation number.';
+              result._upgrade_note = 'Free tier: ' + remaining + ' of ' + effectiveLimit + ' calls remaining. Get 500 calls for $8 at ' + PRO_UPGRADE_URL + ' -- calls never expire. Includes full registered address and HMRC consultation number.';
               result._gated_fields = gated;
             }
 
@@ -590,7 +633,7 @@ const server = http.createServer(async (req, res) => {
               // Gate full reasoning — verdict visible, details gated
               const gated = ['fraud_signals', 'positive_indicators', 'recommended_action', 'summary'];
               gated.forEach(f => delete result[f]);
-              result._upgrade_note = 'Free tier: ' + remaining + ' of ' + FREE_TIER_LIMIT + ' calls remaining. Get 500 calls for $8 at ' + PRO_UPGRADE_URL + ' -- calls never expire. Includes full fraud signal breakdown, positive indicators, and recommended action.';
+              result._upgrade_note = 'Free tier: ' + remaining + ' of ' + effectiveLimit + ' calls remaining. Get 500 calls for $8 at ' + PRO_UPGRADE_URL + ' -- calls never expire. Includes full fraud signal breakdown, positive indicators, and recommended action.';
               result._gated_fields = gated;
             }
 
@@ -598,7 +641,7 @@ const server = http.createServer(async (req, res) => {
               // Gate detail fields — match_status visible, discrepancies gated
               const gated = ['discrepancies', 'name_match', 'address_match', 'recommended_action', 'summary'];
               gated.forEach(f => delete result[f]);
-              result._upgrade_note = 'Free tier: ' + remaining + ' of ' + FREE_TIER_LIMIT + ' calls remaining. Get 500 calls for $8 at ' + PRO_UPGRADE_URL + ' -- calls never expire. Includes full discrepancy analysis and recommended action.';
+              result._upgrade_note = 'Free tier: ' + remaining + ' of ' + effectiveLimit + ' calls remaining. Get 500 calls for $8 at ' + PRO_UPGRADE_URL + ' -- calls never expire. Includes full discrepancy analysis and recommended action.';
               result._gated_fields = gated;
             }