Get VAT Rate for Commodity

Instructions

Implementation Reference

• src/modules/hmrc/tools.py:108-119 (handler)

  The hmrc_get_vat_rate async function is the tool handler. It takes an HMRCVATRateInput (commodity_code string) and returns a VATRate by delegating to the _lookup_vat helper function.

  async def hmrc_get_vat_rate(params: HMRCVATRateInput) -> VATRate:
      """Look up the UK VAT rate for a commodity or service type.
  
      Returns the rate category (standard 20%, reduced 5%, zero 0%, exempt),
      effective date, and any relevant conditions or exceptions.
      Uses a static lookup table current as of 22 Nov 2023 (Autumn Statement).
      Rates may have changed — always verify against GOV.UK for recent Budgets.
  
      Args:
          params: HMRCVATRateInput with the commodity_code (description of goods or service).
      """
      return _lookup_vat(params.commodity_code)

• src/modules/hmrc/tools.py:80-87 (schema)

  HMRCVATRateInput Pydantic model — the input schema for the tool. Accepts a commodity_code string (2-200 chars) describing the goods or service.

  class HMRCVATRateInput(BaseModel):
      model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
  
      commodity_code: str = Field(
          ...,
          description="Commodity code or plain-English description. E.g. 'food', 'domestic fuel', 'software', 'financial services', 'new build residential'",
          min_length=2, max_length=200,
      )

• src/modules/hmrc/models.py:9-22 (schema)

  VATRate Pydantic model — the output schema for the tool. Contains commodity_code, rate (standard/reduced/zero/exempt/outside_scope), rate_percentage, effective_from date, and notes.

  class VATRate(BaseModel):
      """VAT rate for a commodity or service."""
  
      model_config = ConfigDict(str_strip_whitespace=True)
  
      commodity_code: str = Field(..., description="Commodity code or description queried")
      rate: Literal["standard", "reduced", "zero", "exempt", "outside_scope"] = Field(
          ..., description="VAT rate category"
      )
      rate_percentage: float = Field(
          ..., description="Applicable rate as percentage: 20.0 (standard), 5.0 (reduced), 0.0 (zero/exempt)"
      )
      effective_from: date = Field(..., description="Date from which this rate applies")
      notes: str | None = Field(None, description="Any additional notes or conditions on this rate")

• src/modules/hmrc/tools.py:102-119 (registration)

  The register_tools function registers the tool via @mcp.tool decorator with name='get_vat_rate'. The gateway mounts the hmrc_mcp (from __init__.py) under namespace 'hmrc', making the full tool name 'hmrc_get_vat_rate'.

  def register_tools(mcp: FastMCP) -> None:
  
      @mcp.tool(
          name="get_vat_rate",
          annotations={"title": "Get VAT Rate for Commodity", "readOnlyHint": True, "destructiveHint": False, "idempotentHint": True, "openWorldHint": False},
      )
      async def hmrc_get_vat_rate(params: HMRCVATRateInput) -> VATRate:
          """Look up the UK VAT rate for a commodity or service type.
  
          Returns the rate category (standard 20%, reduced 5%, zero 0%, exempt),
          effective date, and any relevant conditions or exceptions.
          Uses a static lookup table current as of 22 Nov 2023 (Autumn Statement).
          Rates may have changed — always verify against GOV.UK for recent Budgets.
  
          Args:
              params: HMRCVATRateInput with the commodity_code (description of goods or service).
          """
          return _lookup_vat(params.commodity_code)

• src/modules/hmrc/tools.py:62-77 (helper)

  _lookup_vat helper function — looks up the commodity code in the static _VAT_LOOKUP dictionary, performing fuzzy matching. Falls back to standard 20% rate if no match found. The lookup table (lines 26-57) has ~30 entries with rate categories, percentages, and explanatory notes.

  def _lookup_vat(commodity_code: str) -> VATRate:
      key = commodity_code.strip().lower()
      for k, (rate_name, percentage, notes) in _VAT_LOOKUP.items():
          if k in key or key in k:
              return VATRate(
                  commodity_code=commodity_code, rate=rate_name,  # type: ignore[arg-type]
                  rate_percentage=percentage, effective_from=_EFFECTIVE_DATE, notes=notes,
              )
      return VATRate(
          commodity_code=commodity_code, rate="standard", rate_percentage=20.0,
          effective_from=_EFFECTIVE_DATE,
          notes=(
              f"No specific exemption found for '{commodity_code}'. "
              "Standard 20% rate assumed. Verify at https://www.gov.uk/guidance/rates-of-vat-on-different-goods-and-services"
          ),
      )