Tax Form Prep

MCP Tool Map

• Evidence documents (primary): paperless.search_documents, paperless.get_document, paperless.download_document — source W-2, 1099, K-1 (authoritative)
• Tax computation: household-tax.assess_exact_support, household-tax.compute_individual_return_exact, household-tax.compute_fiduciary_return_exact
• Reconciliation (secondary): actual-budget.analytics(operation="monthly_summary") — flag income discrepancies, trigger missing-form searches
• Reconciliation (secondary): ghostfolio.portfolio(operation="dividends"), ghostfolio.portfolio(operation="summary") — flag missing 1099-DIV/1099-B, do not use as form input

Adapted from calef/us-federal-tax-assistant-skill (GPLv3 — private use).

Scripts

• scripts/download_irs_forms.py — download IRS PDF forms organized by year; reads scripts/forms-metadata.json for URL construction

Form Location

IRS form PDFs are not bundled with this skill. To get local copies:

cd agent-configs/household-comptroller/scripts
python3 download_irs_forms.py 2025

Forms download to ./forms/<year>/. If the user prefers manual download, direct them to irs.gov/forms-instructions.

4-Phase Workflow

Phase 1: Document Checklist

1. Search Paperless for all tax-year source documents (W-2, 1099 variants, K-1, 1098 variants).
2. Classify each document by IRS form type. See references/irs-form-matrix.md for the complete classification and routing.
3. Generate a completeness checklist: expected documents vs received documents.
4. Flag missing documents with the expected source (employer, bank, brokerage, etc.).

Phase 2: Form Identification

Based on available documents and income types, identify required IRS forms and schedules. Map each source document to the form or schedule it feeds using references/irs-form-matrix.md (covers primary returns, schedules, additional forms, estimated payments, and MA state forms).

Phase 3: Form Completion Guidance

1. For each identified form, provide line-by-line data mapping exclusively from Paperless source documents (W-2, 1099, K-1, 1098, etc.). These are the authoritative figures.
2. Use household-tax.compute_individual_return_exact or household-tax.compute_fiduciary_return_exact for exact computation where supported (2025/2026 US+MA scope). Individual returns support structured itemized deductions and child tax credit (dependents).
3. Flag forms and schedules outside the exact support surface — do NOT estimate; stop and explain the gaps.
4. Reconciliation pass — compare Actual Budget income totals and Ghostfolio dividend/capital gain totals against Paperless documents. Any discrepancy triggers a search for missing forms (e.g., Ghostfolio shows dividends from Fidelity but no 1099-DIV exists → flag as missing and search Paperless). Do NOT use Actual Budget or Ghostfolio figures as form inputs.

Phase 4: Audit Review

1. Math verification: Confirm arithmetic across all forms (totals, carryforwards, cross-form references).
2. Cross-reference consistency: Verify income on Form 1040 matches the sum of all source documents. Verify Schedule D totals match Form 8949 aggregates.
3. Common error checklist:
   • Missing signatures or dates
   • Wrong filing status
   • Forgotten schedules (e.g., Schedule B omitted when interest exceeds $1,500)
   • Mismatched SSN/EIN references
   • Overlooked estimated payment credits
4. State-specific items: Identify MA Form 1 line items that differ from the federal return (5% flat rate, Part B interest/dividends, short-term capital gains rate, no federal Schedule A passthrough).

Output Contract

Always include:

• as_of timestamp
• document completeness matrix (expected vs received, by type and source)
• form/schedule list with exact-support status (supported | unsupported)
• exact computation results where supported (federal + MA)
• unsupported items list with explanation of why they cannot be computed
• audit findings and confidence notes
• provenance trail (document IDs, tool calls, data sources)

Fail-Closed Pattern

Inherits from quarterly-tax: if facts are outside the supported 2025/2026 US+MA scope, stop and explain. Never estimate unsupported tax computations. Never claim exact results when assess_exact_support.supported is false.