# 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-tool-reference.md). 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`

```json
{
  "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](https://www.gov.uk/government/publications/vat-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.