--- name: x12-reader description: >- Parse, read, decode, inspect, or extract data from ANSI X12 EDI documents by calling the Neutron read_x12 MCP tool, which converts raw X12 into structured JSON. Use this skill whenever the user wants to read an X12 or EDI document, inspect an interchange, pull fields from an 850 purchase order, 810 invoice, 856 ASN, 997 functional acknowledgment, or any ISA/GS/ST envelope, including when they paste a blob that starts with `ISA*` or `ISA` plus another delimiter. --- # X12 Reader Convert raw ANSI X12 into structured JSON via the `read_x12` MCP tool, then work with the parsed result. The MCP tool gives you the capability to parse; this skill gives you the workflow for choosing the tool, preserving the input, reading the response, and recovering when something goes wrong. ## When To Reach For This Use this skill when the user asks you to: - Parse, read, decode, explain, inspect, or summarize an X12 or EDI document. - Extract a field such as a PO number, invoice number, ship-to name, control number, or transaction date. - Identify the transaction set in an interchange such as 850, 810, 856, or 997. - Work with a pasted blob that starts with `ISA*` or `ISA` followed by a delimiter. - Generate a 997 Functional Acknowledgment while reading inbound X12. Do not hand-parse X12 yourself. Segment terminators, element separators, component separators, repetition separators, and fixed-width ISA fields vary by interchange. Always route parsing through `read_x12`. If the user asks whether the document is valid, compliant, rejected, or structurally correct, use the companion `validate_x12` workflow instead of inventing a validation option for `read_x12`. ## Tool Inventory - `read_x12`: Parse raw X12 content into structured JSON. Use for inspection, extraction, summarization, envelope analysis, and optional 997 generation. - `validate_x12`: Validate raw X12 content. Use for pass/fail, compliance, and error-list questions, not for routine extraction. - `write_x12`: Generate raw X12 from structured JSON. Do not use it when the user has already supplied raw X12 to inspect. Refer to MCP tools by their bare names, such as `read_x12`. Let the harness resolve any namespace prefix. Do not hardcode harness-specific names like `mcp__neutron__read_x12` or `neutron:read_x12` in reusable skill guidance. ## `read_x12` Parameters - `content` (string, required): Raw X12 EDI interchange content. It must include the ISA segment. - `include997` (boolean, optional): Include a generated 997 Functional Acknowledgment in the result. Defaults to `false`. Preserve the X12 content exactly when calling the tool. Do not trim fixed-width spaces inside the ISA segment. Do not normalize line breaks, delimiters, or trailing segment terminators unless the user explicitly asks you to repair the document. ## Response Shape The tool returns structured content plus serialized JSON text for clients that only consume text. The JSON follows the Neutron read response shape: ```json { "success": true, "version": "004010", "isa": { "InterchangeControlNumber_13": "000000001" }, "iea": { "InterchangeControlNumber_2": "000000001" }, "groups": [ { "gs": { "CodeIdentifyingInformationType_1": "PO" }, "ge": { "GroupControlNumber_2": "1" }, "transactionSets": [ { "ST": { "TransactionSetIdentifierCode_01": "850", "TransactionSetControlNumber_02": "0001" }, "BEG": { "PurchaseOrderNumber_03": "PO-12345" } } ] } ], "ack997": null, "ackTA1": null, "errors": [], "requestId": null, "timestamp": null } ``` Read `isa` and `iea` for interchange metadata. Walk `groups[].transactionSets[]` for documents. Segment objects use EdiFabric-style element names, such as `PurchaseOrderNumber_03` on `BEG`. ## Canonical Workflows ### Field Extraction 1. Identify the raw X12 content and pass it to `read_x12` as `content`. 2. Leave `include997` as `false` unless the user asks for an acknowledgment. 3. Find the transaction set with `ST.TransactionSetIdentifierCode_01`. 4. Read the requested element from the relevant segment or loop. 5. Answer with the extracted value and enough context to show where it came from. ### Document Inspection 1. Call `read_x12` with the full raw interchange. 2. Summarize `isa`, each `gs`, and each transaction set. 3. Highlight control numbers, sender and receiver IDs, dates, transaction counts, and any returned `errors`. 4. Do not dump the full JSON unless the user asks for it. ### Read With 997 Acknowledgment 1. If the user asks for a 997, acknowledgment, FA, or functional acknowledgment, call `read_x12` with `include997: true`. 2. Inspect `ack997` in the response. 3. Return the generated 997 exactly if the user needs to send or save it. 4. If `ack997` is null, report that no 997 was generated and include any `errors` from the response. ### Validation Handoff 1. If the user asks "is this valid," "why was it rejected," or "does it comply," call `validate_x12` instead. 2. Use `read_x12` after validation only if the user also needs extracted data from a parseable document. ## Error Handling - Authentication or authorization failure: tell the user the harness must send `X-API-Key` on MCP requests. Do not ask them to paste keys into chat. - Rate limit failure: report that the Neutron EDI key is rate limited and suggest retrying later or checking account limits. - `isError: true` from `read_x12`: inspect the returned structured content or JSON text for `errors`, then report those errors directly. - `success: false` in the read response: do not trust parsed fields. Explain that parsing failed and include the returned `errors`. - Missing or partial ISA content: ask for the complete interchange including ISA through IEA; fragments cannot be reliably parsed as an interchange. - User needs repair: explain the likely source issue first, then ask before modifying delimiters, segment counts, or envelope values. ## Worked Example User: "Parse this and tell me the PO number: `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*PO123456**20230101~SE*3*0001~GE*1*1~IEA*1*000000001~`" 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*PO123456**20230101~SE*3*0001~GE*1*1~IEA*1*000000001~" } ``` Answer from `groups[0].transactionSets[0].BEG.PurchaseOrderNumber_03`: ```text PO number is PO123456. It came from BEG03 in the 850 purchase order dated 20230101. ``` ## Going Deeper - Load `references/tool-notes.md` for response-shape details, failure interpretation, and parsing conventions. - Load `references/transaction-sets.md` for common X12 transaction-set fields such as 850 purchase order numbers, 810 invoice numbers, 856 shipment IDs, and 997 acknowledgment status.