# X12 Reader Tool Notes

Use these notes after loading `x12-reader/SKILL.md` when you need more detail about the Neutron `read_x12` MCP response or recovery behavior.

## Tool Contract

- Tool name: `read_x12`
- Required parameter: `content` as raw X12 text with an ISA segment.
- Optional parameter: `include997` as a boolean. Use `true` only when a 997 Functional Acknowledgment is requested or useful.
- Tool result: structured content and serialized JSON text containing the same operation response.

## Response Fields

- `success`: `true` when parsing completed. If `false`, do not rely on extracted fields.
- `version`: detected X12 version such as `004010`.
- `isa`: parsed ISA interchange header as a JSON object.
- `iea`: parsed IEA interchange trailer as a JSON object when available.
- `groups`: functional groups, each with `gs`, optional `ge`, and `transactionSets`.
- `ack997`: generated 997 when `include997` is true and a 997 could be produced.
- `ackTA1`: generated TA1 when available.
- `errors`: parse or operation errors.
- `requestId` and `timestamp`: diagnostic metadata when provided by the API path.

## Parameter Conventions

- Keep ISA fixed-width fields exactly as supplied. Spaces in ISA elements are data.
- Include the whole interchange when possible: ISA, GS, ST, transaction body, SE, GE, and IEA.
- Do not add a `Content-Type` value to the MCP tool call. Content type is a REST concern, not a `read_x12` argument.
- Do not add delimiter overrides. The current MCP tool schema does not expose delimiter parameters.

## Recovery Patterns

- If `errors` says the content is invalid or cannot be parsed, ask for the complete original X12 document.
- If the user pasted only transaction-body segments, ask for the ISA and envelope segments before retrying.
- If the user needs an acknowledgment and `ack997` is null, report any returned errors and confirm the source document is a supported X12 transaction.
- If the MCP request itself is unauthorized, rate limited, or fails at transport level, fix the harness/API-key issue before retrying the tool.

## Worked Inspection Pattern

After a successful parse, summarize in this order:

1. Interchange sender, receiver, control number, date, and usage from `isa`.
2. Functional group type and control number from `groups[].gs`.
3. Transaction set ID and control number from each transaction set's `ST`.
4. Business identifiers from transaction-set-specific segments.
5. Any non-empty `errors`, even when the user did not ask for them.