---
name: x12-validator
description: >-
  Validate ANSI X12 EDI documents by calling the Neutron validate_x12 MCP tool.
  Use this skill whenever the user asks whether an X12 or EDI document is valid,
  compliant, acceptable, structurally correct, rejected, broken, or ready to send
  to a trading partner, including 850 purchase orders, 810 invoices, 856 ASNs,
  997 acknowledgments, or any pasted interchange that starts with `ISA*`.
---

# X12 Validator

Validate raw ANSI X12 with the `validate_x12` MCP tool and explain the result in terms a developer or EDI operator can act on.

## When To Reach For This

Use this skill when the user asks:

- "Is this EDI valid?"
- "Why did this X12 get rejected?"
- "Can I send this to my trading partner?"
- "Check this 850, 810, 856, or 997 for errors."
- "Does this ISA/GS/ST envelope look compliant?"

Do not use `read_x12` as a substitute for validation. Parsing is not the same thing as validating against supported X12 specifications.

## Tool Inventory

- `validate_x12`: Validate raw X12 content. Use for correctness, compliance, and pass/fail questions.
- `read_x12`: Parse raw X12 into JSON. Use after validation only when the user also asks for extraction or inspection.
- `write_x12`: Generate raw X12 from structured JSON. Do not use for checking an existing document.

Refer to MCP tools by their bare names, such as `validate_x12`, and let the harness resolve any namespace prefix.

## `validate_x12` Parameters

- `content` (string, required): Raw X12 EDI interchange content. It must include the ISA segment.

Preserve the X12 exactly as supplied. Do not trim ISA spaces or rewrite delimiters before validation unless the user explicitly asks you to repair and retry.

## Response Shape

The tool returns structured content plus serialized JSON text. Validation failures in the document are successful tool calls with `isValid: false`.

```json
{
  "isValid": false,
  "errors": [
    {
      "segment": "BEG",
      "position": 3,
      "message": "Purchase order number is required.",
      "errorCode": "E001"
    }
  ],
  "warnings": [],
  "requestId": null,
  "timestamp": null
}
```

Do not treat `isValid: false` as a tool failure. It is the expected result for an invalid document.

## Canonical Workflows

### Validate A Document

1. Pass the complete raw X12 interchange to `validate_x12` as `content`.
2. Inspect `isValid`, `errors`, and `warnings`.
3. If `isValid` is true, say the document passed validation and mention any warnings.
4. If `isValid` is false, list each error with segment, position, message, and error code when present.
5. Suggest concrete next checks, such as missing required elements, envelope count mismatches, or unsupported transaction-set details.

### Diagnose A Rejection

1. Validate the exact document that was rejected.
2. If the user also has a trading-partner rejection or 997, ask for it or parse it with `read_x12`.
3. Compare validation errors against the rejection details.
4. Explain which issues are source-document defects and which require partner-specific rules not visible to generic validation.

### Validate Then Inspect

1. Run `validate_x12` first for pass/fail.
2. If valid or parseable and the user asks for field details, run `read_x12` next.
3. Keep the validation result separate from extracted business data.

## Error Handling

- `isValid: false`: report document errors. Do not retry unless the user changes the document.
- Non-empty `warnings`: include them after errors or after the pass/fail statement.
- Tool transport error: resolve authentication, rate limit, or server connectivity before retrying.
- Missing ISA or partial content: ask for the full interchange from ISA through IEA.
- Unsupported or partner-specific rule: state what Neutron validation can confirm and what may require trading-partner implementation guidance.

## Worked Example

User: "Is this 850 valid?" followed by an X12 interchange.

Tool call:

```json
{
  "content": "ISA*00*          *00*          *ZZ*SENDER         *ZZ*RECEIVER       *230101*1200*U*00401*000000001*0*P*>~GS*PO*SENDER*RECEIVER*20230101*1200*1*X*004010~ST*850*0001~BEG*00*NE**20230101~SE*3*0001~GE*1*1~IEA*1*000000001~"
}
```

Answer pattern:

```text
This document did not pass validation. BEG element 3 is missing the purchase order number. Correct BEG03 and run validation again before sending it to the trading partner.
```

## Going Deeper

- Load `references/tool-notes.md` for response handling, validation result interpretation, and recovery steps.
- Load `references/transaction-sets.md` for common validation focus areas by transaction set.