VAT Routes, Results and Next Steps

Use this guide to understand VATBuild's project schemes, interpret returned results, and help the user take the next step. VATBuild assesses the VAT treatment; agents should use its results rather than recreate classification rules.

For connection instructions, authentication, tool inputs and error handling, see the MCP Tool Reference. MCP clients should discover the current tool schemas through tools/list.

Project schemes (`claimantRoute`)

claimantRoute identifies the project's scheme. It is different from claimRoute, which describes an individual item's assessed outcome.

`claimantRoute`	Project scheme	Current classification support
`self_build_431nb`	Self-build new dwelling — VAT431NB	Supported
`self_build_431c`	Qualifying conversion — VAT431C	Supported
`self_build_standard`	Standard-rate renovation	Supported; not a 431 refund scheme
`self_build_reduced`	Reduced-rate renovation	Supported; relief at source, not a 431 refund scheme
`developer`	VAT-registered developer	Not yet supported by the classification tools
`contractor`	VAT-registered contractor	Not yet supported by the classification tools

Use a supported, specific route. Do not substitute the generic value self_build. Unsupported routes return ROUTE_NOT_SUPPORTED; do not retry with a different scheme merely to obtain a result.

Confirm the project facts and scheme with the user through VATBuild's project setup. A project should cover one VAT regime; ask the user to complete separate project assessments when more than one applies. Do not infer eligibility from the scheme label alone.

The supported self-build refund schemes concern an HMRC claim. A reduced-rate-at-source project concerns VAT charged by the supplier, not an HMRC refund. VAT-return recovery is a separate process; the presence of developer or contractor vocabulary in saved results does not mean these classification routes are active.

Returned outcomes (`claimRoute`)

Use the returned claimRoute to interpret the result, not to predict what a particular invoice should produce. The following values may be encountered across classification responses and saved line items.

`claimRoute`	Meaning	Next step
`hmrc_refund`	Potential recovery through an HMRC 431 claim	Include only the approved amount in the appropriate claim workflow
`full_hmrc_refund`	Full recovery through an HMRC 431 claim	Use the returned approved amount
`zero_at_source`	Correct zero-rate treatment at source	Follow the returned explanation; do not create a refund from the rate alone
`reduced_at_source`	Correct reduced-rate treatment at source	No HMRC refund implied
`input_tax`	Recovery through a VAT return	Follow the relevant VAT-return process
`supplier_correction`	Supplier invoice correction needed	Ask the user to obtain a corrected invoice or credit note
`undercharged_vat`	Possible supplier undercharge	Raise the issue with the supplier; do not treat it as a refund
`esm_zero_rate`	Energy-saving-materials zero-rate outcome	Follow the returned explanation and review status
`not_reclaimable`	Not recoverable under this assessment	Do not include in a claim
`input_tax_blocked`	Input-tax recovery blocked	Do not include in VAT-return recovery
`split_required`	Supplier-issued separation needed	Request separately itemised lines or an amended invoice; do not calculate a split
`reverse_charge_cis`	Domestic reverse-charge outcome	Follow the returned instructions and seek appropriate review
`outside_scope`	Outside the scope of UK VAT	Follow the returned explanation
`pending`	More information or review needed	Provide verified facts or complete review in VATBuild
`pending_complex_answer`	A follow-up VAT question is unresolved	Follow the question-handling guidance below

Not every tool returns every value. An outcome value is not a guarantee of eligibility, approval or submission readiness. If a result is unfamiliar, preserve the response and direct the user to review it rather than inventing a treatment.

Pending results and user confirmation

Only reviewStatus: "approved" amounts may be presented as confirmed claim amounts. Do not include pending, rejected or no-action items in confirmed claim totals.
A pending result or provisional: true is an unconfirmed estimate. Do not describe its reclaimAmount as money the user will receive.
Do not decide legally significant facts on the user's behalf. Present the question, obtain the user's explicit confirmation and submit only their confirmed answer.
Use the question text and permitted answers supplied by the relevant interface. Do not hardcode category-specific questions or assume all answers are true / false.
check_line_item can supply structured question text and allowedAnswers. Saved-item tools do not supply current question text or allowed answers, and answer responses do not supply the next question. Do not derive questions from vatComplexType or rule explanations; when exact metadata is unavailable, direct the user to the item's review in the VATBuild web app.
A follow-up answer may leave the item pending or require another question. Read the new result rather than assuming one answer completes review.
If an answer response returns data.crossItemContextRequired: true, use reclassify_companion_items for the relevant document as instructed by the MCP Tool Reference, then retrieve the updated results.

Supplier corrections versus HMRC claims

These are different actions and must stay separate in user-facing summaries:

HMRC claim: use the approved amounts and the claim report's readiness information. Obtain the final submission files through the VATBuild web app.
Supplier correction: the supplier must correct the invoice or issue a credit note. Do not present this amount as directly recoverable from HMRC.
Split required: ask the supplier to provide correctly separated invoice lines or an amended invoice. Do not estimate, apportion or invent the split amounts yourself. Submit the corrected invoice for assessment.

Use the amounts and instructions VATBuild returns. Do not calculate a claim or supplier correction by comparing VAT percentages yourself. Where the response marks a rate as informational or includes warnings, do not use that rate to derive a monetary outcome.

Supply facts (`supplyType`)

Where a tool accepts supplyType, provide the verified nature of the supply. These values describe invoice facts, not a promise of tax treatment.

`supplyType`	Description
`labour`	Labour-only service
`subcontractor`	Work supplied by a subcontractor
`materials`	Goods supplied without installation
`supply_and_install`	Goods supplied and installed by the same supplier
`installation_service`	Installation service
`professional_services`	Professional services, such as design or surveying

If the facts are unclear, ask the user or pass null where the tool schema permits it. Do not select a value because it might produce a more favourable outcome. Use only recognised identifiers supplied by VATBuild; do not guess taxonomy names or optional classification hints.

Explanations and references

Read the explanation returned for the particular item:

rule.label: a short description of the assessment.
rule.noticeRef: the applicable HMRC reference, where supplied.
rule.explanation: the explanation and any next action.
firedRuleId: an opaque rule identifier, where supplied. Do not parse its structure or use it to reconstruct decision rules; use the documented outcome and action fields.

Some tools return rule or firedRuleId as null. Preserve that distinction; do not invent a rule or HMRC reference to fill the gap.

The guide does not provide an exhaustive eligibility or exclusion checklist. Review individual results in their project context and refer uncertain cases to the VATBuild review workflow or a suitably qualified adviser.

Minimal integration example

This REST request illustrates the request structure only. Replace the description, amounts and project context with verified facts. For MCP calls, use the current tools/list input schema instead of assuming REST and MCP inputs are identical.

POST /api/v1/check-line-item


{
  "context": {
    "claimantRoute": "self_build_431nb",
    "projectType": "New build",
    "newDwelling": "yes",
    "buildingType": "detached house"
  },
  "item": {
    "lineText": "Description exactly as shown on the invoice",
    "netAmount": "100.00",
    "vatCharged": "20.00"
  }
}

No tax outcome is implied by this example. On a successful response:

1. Read the assessment from response.data.outcome, including claimRoute and reviewStatus.

2. Read response.data.reclaimAmount as a decimal string, not a guaranteed refund.

3. Check returned warnings and action information before presenting an amount.

4. Present the available explanation; obtain further information or user review where requested.

Handle unsuccessful responses using the tool reference's error guidance. check_line_item does not save the assessment to a project.

HMRC reference

HMRC Notice 708 — Buildings and Construction

Public HMRC guidance explains the legislation. VATBuild's returned assessment explains its application to the submitted facts; neither a scheme label nor this integration guide replaces review of those facts.