--- name: x12-writer description: >- Generate ANSI X12 EDI documents by calling the Neutron write_x12 MCP tool, which converts structured X12 JSON with ISA, Groups, GS, and Transactions into raw X12 text. Use this skill when the user wants to create, generate, emit, build, or draft X12 or EDI output such as an 850 purchase order, 810 invoice, 856 ASN, or 997 acknowledgment from structured data or JSON. --- # X12 Writer Generate raw ANSI X12 from structured JSON through the `write_x12` MCP tool. This skill focuses on shaping the JSON, choosing envelope values, interpreting write errors, and returning generated EDI safely. ## When To Reach For This Use this skill when the user asks you to: - Generate X12 or EDI from JSON or business data. - Build an 850 purchase order, 810 invoice, 856 ASN, or 997 acknowledgment. - Convert structured X12 JSON into raw EDI text. - Fix a `write_x12` request shape that failed before generation. Do not use this skill to parse existing X12. Use `x12-reader` and `read_x12` for inspection. Do not use it to decide whether an existing document is valid. Use `x12-validator` and `validate_x12` for validation. ## Tool Inventory - `write_x12`: Generate raw X12 EDI content from structured X12 JSON. - `validate_x12`: Validate generated X12 before the user sends it. - `read_x12`: Parse generated X12 back to JSON when the user wants a round-trip inspection. Refer to MCP tools by their bare names, such as `write_x12`, and let the harness resolve any namespace prefix. ## `write_x12` Parameters - `content` (object, required): Structured X12 JSON with `ISA`, `Groups`, each group's `GS`, and `Transactions`. `IEA` is optional in the MCP contract. The first group and first transaction drive the current write operation. Make sure `Groups[0].GS.VersionAndRelease_8` and `Groups[0].Transactions[0].ST.TransactionSetIdentifierCode_01` are present. ## Required JSON Shape Use this outer MCP argument shape: ```json { "content": { "ISA": { "AuthorizationInformationQualifier_1": "00", "AuthorizationInformation_2": " ", "SecurityInformationQualifier_3": "00", "SecurityInformation_4": " ", "SenderIDQualifier_5": "ZZ", "InterchangeSenderID_6": "SENDER ", "ReceiverIDQualifier_7": "ZZ", "InterchangeReceiverID_8": "RECEIVER ", "InterchangeDate_9": "230101", "InterchangeTime_10": "1200", "InterchangeControlStandardsIdentifier_11": "U", "InterchangeControlVersionNumber_12": "00401", "InterchangeControlNumber_13": "000000001", "AcknowledgementRequested_14": "0", "UsageIndicator_15": "P", "ComponentElementSeparator_16": ">" }, "Groups": [ { "GS": { "CodeIdentifyingInformationType_1": "PO", "SenderIDCode_2": "SENDER", "ReceiverIDCode_3": "RECEIVER", "Date_4": "20230101", "Time_5": "1200", "GroupControlNumber_6": "1", "TransactionTypeCode_7": "X", "VersionAndRelease_8": "004010" }, "Transactions": [ { "ST": { "TransactionSetIdentifierCode_01": "850", "TransactionSetControlNumber_02": "0001" } } ] } ] } } ``` ## Response Shape ```json { "success": true, "ediContent": "ISA*00*...~", "errors": [], "requestId": "...", "timestamp": "2026-05-25T00:00:00Z" } ``` If `success` is false or the tool marks the call as an error, report `errors` and fix the JSON shape before retrying. ## Canonical Workflows ### Generate From Structured JSON 1. Confirm the user has supplied or approved envelope values: sender, receiver, dates, times, control numbers, usage indicator, and version. 2. Build `content.ISA`, `content.Groups[0].GS`, and `content.Groups[0].Transactions[0]` using Neutron's exact property names. 3. Call `write_x12`. 4. Return `ediContent` exactly as generated. 5. Offer to run `validate_x12` on the generated result before sending. ### Repair A Failed Write 1. Read the returned `errors`. 2. Check for missing `ISA`, `Groups`, `GS`, or `Transactions` first. 3. Check `GS.VersionAndRelease_8` and `ST.TransactionSetIdentifierCode_01` next. 4. Fix only the missing or malformed fields. 5. Retry `write_x12` once with the corrected JSON. ## Error Handling - Missing `Groups`: add a `Groups` array with at least one group. - Missing `ISA`: add the `ISA` object with required interchange fields. - Missing first `GS`: add `Groups[0].GS`. - Missing transaction: add `Groups[0].Transactions` with at least one transaction. - Generation failure after shape checks: report `errors` and ask whether the user wants to adjust the transaction data or version. - Authentication, rate limit, or transport failure: fix harness/API-key access before changing document JSON. ## Worked Example User: "Generate a minimal 850 from this JSON." Tool call: ```json { "content": { "ISA": { "AuthorizationInformationQualifier_1": "00", "AuthorizationInformation_2": " ", "SecurityInformationQualifier_3": "00", "SecurityInformation_4": " ", "SenderIDQualifier_5": "ZZ", "InterchangeSenderID_6": "SENDER ", "ReceiverIDQualifier_7": "ZZ", "InterchangeReceiverID_8": "RECEIVER ", "InterchangeDate_9": "230101", "InterchangeTime_10": "1200", "InterchangeControlStandardsIdentifier_11": "U", "InterchangeControlVersionNumber_12": "00401", "InterchangeControlNumber_13": "000000001", "AcknowledgementRequested_14": "0", "UsageIndicator_15": "P", "ComponentElementSeparator_16": ">" }, "Groups": [ { "GS": { "CodeIdentifyingInformationType_1": "PO", "SenderIDCode_2": "SENDER", "ReceiverIDCode_3": "RECEIVER", "Date_4": "20230101", "Time_5": "1200", "GroupControlNumber_6": "1", "TransactionTypeCode_7": "X", "VersionAndRelease_8": "004010" }, "Transactions": [ { "ST": { "TransactionSetIdentifierCode_01": "850", "TransactionSetControlNumber_02": "0001" }, "BEG": { "TransactionSetPurposeCode_01": "00", "PurchaseOrderTypeCode_02": "NE", "PurchaseOrderNumber_03": "PO123456", "Date_05": "20230101" } } ] } ] } } ``` Answer from `ediContent`: ```text Generated X12: ISA*00*...~ ``` ## Going Deeper - Load `references/tool-notes.md` for shape rules, response interpretation, and write-error recovery. - Load `references/transaction-sets.md` for starter segment notes by transaction set.