Agent playbook

MOCK server. Nothing here files, extends, pays or registers anything with the IRS. "Accepted" from this server means only that the mock's own illustrative rules passed. Never tell a human a return was filed, accepted or rejected by the IRS.

Hard rules (never)

1. Never invent, guess, or "make plausible" an EIN, SSN, ETIN, EFIN, PIN, bank routing/account number or Software ID. Use only the fake test values the mock expects (EIN 00-NNNNNNN, SSN NNN-00-NNNN such as 000-00-0000, routing 000000000). If the human supplies what looks like a real identifier, stop and tell them this mock is for fake data only; do not echo it into tool calls, logs or files.
2. Never file with, or send data to, the IRS or any real e-file service based on mock output, and never present mock output as filing evidence. Mock XML is illustrative and not schema-valid.
3. Never submit without explicit human authorization for that specific submission (see checklist). Even for the mock, ask first when the data came from a human or a real client file.
4. Never work around unavailable forms: 940, 945, 1120-S and 8868 are not available to this company. Do not substitute another form type or returnType.
5. Do not use forceReject, 99-9999999, or production indicators except when the human asks you to test those paths.
6. No tax advice: report what the mock computed and what the cited IRS pages say; send judgments (eligibility, penalties, elections) to a human.

Recommended sequence

1. list_supported_forms: confirm the form is modeled by the mock and read its field names. Stop if the form is 940/945/1120-S/8868/943.
2. Assemble data from human-provided fake values. Leave stated out unless the human gave totals to cross-check.
3. validate_return. Loop: read errors (fix each by path; see the error catalog), re-validate until valid: true. Read warnings and surface them to the human; do not hide them. Check xsd.status: not_available is normal and means no schema validation happened.
4. build_return_xml. Confirm validation.valid is true (XML may be returned even with business-rule errors) and show/keep the XML as illustrative only.
5. Human checkpoint (below).
6. mock_submit_return once. Save the submissionId and messageId.
7. get_acknowledgement with that ID. If status is Processing (kind: StatusRecord) wait briefly and poll again, up to a sensible cap (for example 10 polls, 2-5 seconds apart); a status record is not proof of acceptance. As shipped, this server answers with the final result on the first call. On Rejected, read errors[], fix the data, and start again from step 3; a rejected submission does not block a corrected one. On Accepted, still read warnings[].

Idempotency and retries

• validate_return, build_return_xml, list_supported_forms, get_acknowledgement are safe to repeat.
• mock_submit_return is NOT idempotent: each call mints a new submissionId. If the call returned a submissionId, never retry; poll instead. If the call failed with no ID (transport error), you cannot tell whether it landed: call get_acknowledgement only if you have an ID, otherwise tell the human and resubmit once at most.
• Resubmitting identical data after an Accepted result gets R0000-902-01 (duplicate) on the new submission. Duplicate detection key: form + EIN (or fake SSN for 4868) + tax year + period (941: Q1-Q4; 941-X: Qn-Xk with correctionSequence; 7004: returnType + period end).
• State is in memory per server process. Restarting the server or starting a new Claude session loses all submission IDs (get_acknowledgement then returns "Unknown submissionId"). Record IDs you need in your notes.
• SCHEMA errors are never retried unchanged; fix the data.

What to ask the human before submitting

• Confirm the data are test/fake values and that this is a mock run, not a real filing.
• Which form, period (year, quarter or period end) and filer name; who supplied each number.
• For 941/944: deposit schedule and that monthly/daily liabilities were provided by them, not estimated. For 944: whether the IRS actually notified the employer (tool flag irsNotifiedToFile944).
• For 4868/7004 with payment: payment method, and who authorizes it (signature option or ACH agreement); never fill bank details yourself.
• Any warnings they accept, and an explicit "yes, submit this to the mock".
• If anything real is intended afterward (an actual filing), say clearly that this tool cannot do it and a human must use IRS-approved software or a professional.

Reporting back

State: which tool calls ran, valid, error/warning codes with their basis, the submissionId, final mock status, and the sentence "MOCK result; nothing was sent to the IRS."