suggest_vat_treatment

Instructions

Implementation Reference

• index.js:930-941 (registration)

  Registration of the 'suggest_vat_treatment' tool with input/output schemas and annotations.

  // ── 27. Suggest VAT Treatment ──
  server.registerTool("suggest_vat_treatment", {
    description: "Suggests the likely VAT treatment for a transaction based on seller country, buyer country, buyer VAT registration status, and goods/services type — covering standard VAT, reverse charge, OSS/IOSS, and zero-rating scenarios under EU VAT rules. Returns { treatment, description, seller_charges_vat, applicable_rate, notes, disclaimer }. Use when building checkout VAT logic, invoice generation, or cross-border EU compliance workflows. For digital services sold to EU consumers, OSS is indicated automatically. Always verify with a tax advisor for real transactions.",
    inputSchema: {
      seller_country: z.string().describe("Seller's country ISO code. Example: 'PT'"),
      buyer_country: z.string().describe("Buyer's country ISO code. Example: 'DE'"),
      buyer_is_vat_registered: z.boolean().describe("Whether the buyer is VAT registered (B2B) or not (B2C)"),
      goods_type: z.enum(["goods", "digital_services", "services"]).describe("Type of supply")
    },
    outputSchema: { treatment: z.string(), description: z.string(), seller_charges_vat: z.boolean(), applicable_rate: z.string(), seller_country: z.string(), buyer_country: z.string(), buyer_is_vat_registered: z.boolean(), goods_type: z.string(), notes: z.string(), disclaimer: z.string() },
        annotations: { title: "Suggest VAT Treatment", readOnlyHint: true, idempotentHint: true, openWorldHint: false }
  }, async ({ seller_country, buyer_country, buyer_is_vat_registered, goods_type }) => {

• index.js:941-1003 (handler)

  Handler function implementing the VAT treatment suggestion logic. Evaluates seller/buyer countries, VAT registration status, and goods/services type to determine domestic VAT, reverse charge, OSS, export zero-rating, import, or out-of-EU treatment.

  }, async ({ seller_country, buyer_country, buyer_is_vat_registered, goods_type }) => {
    const seller = seller_country.toUpperCase();
    const buyer = buyer_country.toUpperCase();
    const euCountries = ["AT","BE","BG","HR","CY","CZ","DK","EE","FI","FR","DE","GR","HU","IE","IT","LV","LT","LU","MT","NL","PL","PT","RO","SK","SI","ES","SE"];
    const sellerInEU = euCountries.includes(seller);
    const buyerInEU = euCountries.includes(buyer);
  
    let treatment, description, sellerChargesVat, applicableRate, notes;
  
    if (seller === buyer) {
      treatment = "domestic_vat";
      description = "Domestic transaction — standard VAT of seller country applies";
      sellerChargesVat = true;
      applicableRate = "Seller country standard/reduced rate";
      notes = `Apply ${seller} VAT rates. Standard transaction.`;
    } else if (sellerInEU && buyerInEU && buyer_is_vat_registered) {
      treatment = "intra_eu_b2b_reverse_charge";
      description = "Intra-EU B2B supply — reverse charge mechanism applies";
      sellerChargesVat = false;
      applicableRate = "0% (zero-rated at source)";
      notes = `Seller issues zero-rated invoice. Buyer self-accounts for VAT in ${buyer} at local rate. Seller must quote buyer's VAT number on invoice.`;
    } else if (sellerInEU && buyerInEU && !buyer_is_vat_registered) {
      if (goods_type === "digital_services") {
        treatment = "oss_digital_services";
        description = "Intra-EU B2C digital services — OSS (One Stop Shop) scheme";
        sellerChargesVat = true;
        applicableRate = `${buyer} country rate for digital services`;
        notes = `VAT charged at buyer's country rate. Declare and pay via OSS scheme. No need to register in ${buyer} if using OSS.`;
      } else if (goods_type === "goods") {
        treatment = "eu_distance_sales";
        description = "Intra-EU B2C goods — distance selling rules / OSS";
        sellerChargesVat = true;
        applicableRate = `${buyer} country rate (if above €10,000 EU threshold)`;
        notes = `Below €10,000 annual EU B2C threshold: apply seller country VAT. Above threshold: apply buyer country VAT via OSS.`;
      } else {
        treatment = "b2c_services_seller_country";
        description = "Intra-EU B2C services — general rule: seller country VAT";
        sellerChargesVat = true;
        applicableRate = `${seller} country rate`;
        notes = "General rule for B2C services: place of supply is seller's country. Exceptions apply for specific service types (transport, cultural, etc.).";
      }
    } else if (sellerInEU && !buyerInEU) {
      treatment = "export_zero_rated";
      description = "Export outside EU — zero-rated supply";
      sellerChargesVat = false;
      applicableRate = "0% (export)";
      notes = `Supply to ${buyer} outside EU. Zero-rated export. Seller must retain export documentation. ${buyer === "UK" ? "Post-Brexit: UK is treated as third country." : ""}`;
    } else if (!sellerInEU && buyerInEU) {
      treatment = "import_buyer_accounts";
      description = "Import from outside EU — buyer accounts for import VAT";
      sellerChargesVat = false;
      applicableRate = `${buyer} import VAT rate`;
      notes = `Goods/services from outside EU. ${buyer} import VAT applies. For digital services B2C: seller may need to register for IOSS.`;
    } else {
      treatment = "outside_eu_scope";
      description = "Transaction outside EU VAT scope";
      sellerChargesVat = false;
      applicableRate = "N/A";
      notes = "Neither seller nor buyer is in the EU. EU VAT rules do not apply.";
    }
  
    return { content: [{ type: "text", text: JSON.stringify({ treatment, description, seller_charges_vat: sellerChargesVat, applicable_rate: applicableRate, seller_country: seller, buyer_country: buyer, buyer_is_vat_registered, goods_type, notes, disclaimer: "Reference information only — not legal or tax advice. Always verify with a qualified tax advisor for real transactions." }) }] };
  });