AI Accountant Workpapers for Complex Tax Returns
Trace each reported value to a source-linked workpaper, surface conflicting facts, and prepare the questions a reviewer must resolve before filing.
Maya needs more than another assistant summarizing her tax folder. She needs someone to answer why a number appears in the draft, which document supports it, what changed since last year, and what must be resolved before a return can be approved.
An AI accountant for complex tax returns should produce workpapers, records that show how reported values were assembled, and an exception queue. It can reduce the time spent opening PDFs, copying values, matching transactions, and finding missing records. Uncertain tax positions must remain visibly unresolved.
This article uses “AI accountant” as a product label for an evidence-handling preparation system. It is not tax advice, and a taxpayer or qualified professional must make the final filing decisions.
The agent-app pattern below keeps one sandbox per customer, with the client’s documents on its filesystem.
Every proposal the agent makes goes through a submit_proposal tool call.
The host queues it as queued_for_approval, and nothing is filed until a human approves it.
A reader can check each run’s turn.state, the tool loop’s stopReason, and each proposal’s queue status.
The useful unit is a claim with a citation
The smallest useful unit is a claim with its source, status, calculation impact, and history.
Maya’s folder might contain:
| Record | Candidate claim | Question left open |
|---|---|---|
| Form W-2 (wage and withholding statement) | wages and withholding for the tax year | does it cover every employer? |
| brokerage statement | proceeds and reported basis, the tax cost used to measure gain or loss | which acquisition lot is connected? |
| partnership agreement | 20% ownership | did the percentage change before year end? |
| Schedule K-1 (pass-through tax statement) | 15% ownership and pass-through items | which source controls the draft? |
| wallet export | transfers and digital-asset dispositions | which addresses belong to Maya? |
| prior return | carryovers and prior positions | did a later correction change the starting value? |
The Internal Revenue Service (IRS) digital-asset guidance says taxpayers need records that establish positions taken on a federal return. The IRS page for Form 8949, the form used to reconcile many sales and exchanges, describes reconciling reported amounts with the amounts reported on the return. Those sources justify preserving source links. They do not authorize an AI model to decide every digital-asset event.
The agent reads the client’s documents in one sandbox
client.instances.ensure is keyed by the customer, so each customer reaches one sandbox.
instance.box.write puts a document on that filesystem, and instance.turn asks the agent on a thread.
While the turn’s state is running, the sandbox keeps working; asking again with the same turnId settles it.
import { readFile } from "node:fs/promises";
import { Sandbox } from "@tangle-network/sandbox";
const client = new Sandbox({
apiKey: process.env.TANGLE_API_KEY!,
baseUrl: "https://sandbox.tangle.tools",
});
// One sandbox per customer. The platform keeps it, resumes it, replaces it.
export async function review(customerId: string, turnId: string, contract: string) {
const instance = await client.instances.ensure({
key: `customer:${customerId}`,
profile: {
version: "contracts-v1",
backend: {
type: "opencode",
profile: {
name: "contract-review",
prompt: {
systemPrompt: "You review contracts. Cite the clause for every finding.",
},
},
},
},
create: { resources: { cpuCores: 1, memoryMB: 2048, diskGB: 10 } },
});
await instance.box.write("contracts/msa.md", contract);
const ask = "Review contracts/msa.md. List the indemnity, liability and termination risks.";
let turn = await instance.turn(ask, { thread: "main", turnId });
// Same turnId: pick the turn back up.
while (turn.state === "running") {
await new Promise((wait) => setTimeout(wait, 3_000));
turn = await instance.turn(ask, { thread: "main", turnId });
}
return turn.state === "completed" ? turn.text : turn.state;
}
console.log(await review("acme", "review-1", await readFile("msa.md", "utf8")));The run shows that the agent received the file and returned a completed answer.
It does not show that the answer is correct.
The claim ledger still needs the source page and a reviewer decision.
A claim ledger makes uncertainty inspectable
The claim ledger uses separate fields for extracted text, normalized values, review state, and source evidence. An empty field should never become a confirmed zero without an explicit decision.
The following is illustrative TypeScript for an application model, not a Tangle SDK type.
type ReviewState =
| 'candidate'
| 'needs-review'
| 'accepted'
| 'rejected'
| 'superseded'
type Claim = {
id: string
field: string
originalValue: string
normalizedValue?: string | number
source?: {
document: string
page?: number
excerpt: string
}
state: ReviewState
affects: string[]
}
const claim: Claim = {
id: 'claim-ownership-001',
field: 'partnership.ownership',
originalValue: 'Maya Stone: twenty percent interest',
normalizedValue: 0.2,
source: {
document: 'partnership-agreement.pdf',
page: 4,
excerpt: 'Maya Stone: twenty percent interest',
},
state: 'needs-review',
affects: ['K-1 allocation', 'state allocation'],
}
console.log(claim)
The claim stays in needs-review even though it has a page reference.
A citation proves where the text came from.
It does not prove that the document is current, controlling, or interpreted correctly.
Reconciliation is a product feature
Reconciliation compares records that describe the same field or transaction, before the system totals or drafts schedules.
Consider Maya’s 20% agreement and 15% K-1. An ordinary data-entry tool imports the K-1 and moves on. An AI accountant puts both records in front of a reviewer:
| Field | Source A | Source B | Downstream effect |
|---|---|---|---|
| ownership | 20% in agreement, page 4 | 15% on K-1, page 2 | pass-through and state amounts may change |
| effective date | March 3, 2025 | January 31, 2026 | determine which period each source describes |
| source type | governing document candidate | entity-issued tax statement | ask taxpayer or advisor which controls |
| status | needs review | needs review | block dependent draft lines |
The same screen handles duplicate uploads, a transfer that appears in two wallet exports, and an amount whose currency or conversion date was never recorded.
The system keeps a conflict rather than collapsing it. This JSON example keeps both values:
{
"field": "partnership.ownership",
"values": [
{
"value": 0.2,
"document": "partnership-agreement.pdf",
"page": 4
},
{
"value": 0.15,
"document": "k1-statement.pdf",
"page": 2
}
],
"state": "needs-review",
"question": "Which ownership record governs the return period?"
}
Calculate from structured facts
After review, deterministic code calculates narrow quantities from typed inputs. The model may help extract a number, but the number’s meaning must also live in typed code.
Maya has $180,000 of wages, $2,400 of interest, and $25,000 of proceeds from a digital-asset disposition. Her acquisition record is missing, so the system reports $182,400 of ordinary-income candidates and leaves the gain candidate unresolved. “Ordinary-income candidates” is a preparation label for amounts routed to ordinary-income review, not a completed tax classification.
type ReturnInputs = {
wages: number
interest: number
proceeds: number
basis: number | null
}
type ReturnSummary = {
ordinaryIncomeCandidates: number
gainCandidate: number | null
questions: string[]
}
function summarize(input: ReturnInputs): ReturnSummary {
const questions = input.basis === null
? ['Provide acquisition records before calculating gain or loss.']
: []
return {
ordinaryIncomeCandidates: input.wages + input.interest,
gainCandidate: input.basis === null
? null
: input.proceeds - input.basis,
questions,
}
}
const summary = summarize({
wages: 180_000,
interest: 2_400,
proceeds: 25_000,
basis: null,
})
console.assert(summary.ordinaryIncomeCandidates === 182_400)
console.assert(summary.gainCandidate === null)
console.assert(summary.questions.length === 1)
This is a workpaper calculation, not a tax-liability estimate. The IRS Form 1099-DA guidance explains that a broker’s digital-asset statement may report proceeds and in some cases basis, while the taxpayer remains responsible for reporting income, gains, and losses. An AI accountant should show whether a statement supplied basis or whether the value came from a separate acquisition record.
Where Tangle fits in the work session
Tangle coordinates reusable service packages and the operators that run them. The Sandbox product provides the isolated runtime for agent jobs. The product described here is an illustrative Tangle Tax Agent architecture, not a claim that Tangle currently offers accounting or tax advice.
The Tangle Blueprint documentation defines a Blueprint as a reusable service template.
For this workflow, a Blueprint could describe a prepare-workpapers job, its accepted input package, its review-package output, and its storage requirements.
- A service instance is one live deployment of that Blueprint. An operator runs it.
- A runtime is the isolated environment where the parser, model calls, calculators, and document store operate.
- An agent profile pins the model, tools, budget, and policies for Maya’s run.
- A Tangle Router selects an operator or provider route for a model request. It does not choose a tax position.
- A trace records the files opened, tools called, outputs produced, reviewer decisions, and failures.
- An evaluation runs known cases and checks result, cost, and policy behavior. The set should include conflicting ownership, missing basis, duplicate uploads, unreadable scans, and an amended K-1.
- Attestation is a signed report on measured code and hardware-backed execution, when the runtime uses one. It supports a privacy or code-identity claim, not a claim that the conclusion is correct.
- x402 is an HTTP payment flow: a request returns
402 Payment Requiredand accepts payment proof on retry. On Tangle’s asynchronous Blueprint gateway, settlement admits the job with202 Accepted, and the runner delivers the result separately. Payment proves the request was paid. It does not prove the workpaper is accurate or complete.
These terms follow Tangle’s core concepts page. The x402 standard documentation describes payment over HTTP.
The Sandbox quickstart shows the public SDK. Its health check runs before any synthetic documents are uploaded:
npm install @tangle-network/sandbox
curl -fsS https://sandbox.tangle.tools/health
That command tests reachability only. It does not establish retention, isolation, tax-rule coverage, or the quality of a generated workpaper.
Route filing through submit_proposal
The agent never files. It calls submit_proposal, and the handler queues the call for a certified human.
buildAppToolOpenAITools advertises the four app tools, createAppToolRuntimeExecutor validates each call and routes it to the handlers, and runAppToolLoop re-runs the model until it stops.
Dispatch stamps regulated on each regulatedTypes entry, and the handler must queue those rather than execute them.
The same tool names apply when a sandboxed agent runs the turn.
import { buildAppToolOpenAITools, createAppToolRuntimeExecutor, type AppToolHandlers, type AppToolTaxonomy } from '@tangle-network/agent-app/tools'
import { createOpenAICompatStreamTurn, runAppToolLoop, type LoopMessage, type ToolLoopEvent } from '@tangle-network/agent-app/runtime'
const taxonomy: AppToolTaxonomy = { proposalTypes: ['file-return', 'amend-return', 'open-question'], regulatedTypes: ['file-return', 'amend-return'] }
// A product writes proposals to its own store. This list only shows the shape.
const queue: Array<{ proposalId: string; type: string; title: string }> = []
const handlers: AppToolHandlers = {
async submitProposal(args) {
const proposalId = `proposal-${queue.length + 1}`
queue.push({ proposalId, type: args.type, title: args.title })
return { proposalId, deduped: false, status: 'queued_for_approval' }
},
async scheduleFollowup(args) { return { id: `followup-${args.dueDate}`, dueDate: args.dueDate, deduped: false } },
async renderUi(args) { return { path: 'workpapers/summary.json', content: JSON.stringify(args.schema) } },
async addCitation(args) { return { citationId: `cite-${args.path}`, path: args.path } },
}
const tools = buildAppToolOpenAITools(taxonomy)
const model = createOpenAICompatStreamTurn({ baseUrl: 'https://router.tangle.tools/v1', apiKey: process.env.TANGLE_API_KEY!, model: 'glm-5.3', tools })
// The model turn also yields reasoning and usage events; the loop reads text and tool calls.
async function* streamTurn(messages: LoopMessage[]): AsyncGenerator<ToolLoopEvent> {
for await (const event of model(messages)) {
if (event.type === 'text' || event.type === 'tool_call') yield event
}
}
const result = await runAppToolLoop({
systemPrompt: 'Prepare the 2025 workpapers. Propose a file-return only after every fact is accepted.',
userMessage: 'Wages $180,000, interest $2,400, proceeds $25,000, basis missing. Propose the next step.',
streamTurn,
executeToolCall: createAppToolRuntimeExecutor({ handlers, taxonomy, ctx: { userId: 'maya-stone', workspaceId: 'client-2025', threadId: 'return-2025' } }),
isExecutableTool: (name) => tools.some((tool) => tool.function.name === name),
maxToolTurns: 12,
})
console.log(result.stopReason, queue)
The fence proves that a proposal reaches the queue as queued_for_approval in this process.
It does not prove the approval screen, the filing service, or the reviewer’s decision.
The packet should survive a handoff
An advisor should receive a packet that can be reviewed without replaying the AI conversation. Its source index lists every input file, page reference, processing result, and missing record. For Maya, the packet contains:
| Packet section | Contents | Reviewer action |
|---|---|---|
| source index | every file, page count, year, owner, and processing result | confirm the input set |
| fact ledger | original value, normalized value, source, state, and history | accept, reject, or correct facts |
| calculation workpapers | inputs, units, rule version, and outputs | reproduce or challenge calculations |
| reconciliation report | conflicts, duplicates, unmatched transfers, and late records | resolve or escalate issues |
| missing-fact list | requested document and the decision it would unblock | collect the right evidence |
| draft forms | forms and schedules marked unapproved | review the proposed filing |
| correction log | old value, new value, reviewer, and timestamp | understand version changes |
The packet uses version identifiers. If Maya supplies a corrected K-1, the product shows which calculations and draft lines changed, and it does not overwrite the old result.
The change trail should explain a revision
Suppose the first draft uses the 15% K-1 allocation while the partnership agreement is still needs-review. Maya then uploads an amended K-1 that applies to the full tax year. That changes a tax fact, so dependent outputs must be recalculated.
| Event | Fact state | Required product response |
|---|---|---|
| first K-1 received | 15% candidate, source page 2 | keep dependent lines provisional |
| agreement conflict found | 20% and 15% both need review | ask which record controls the period |
| amended K-1 received | 20% accepted by reviewer | create a new draft version and recalculate |
| reviewer opens the packet | old and new values visible | show which forms and totals changed |
The model can suggest that the amended document supersedes the earlier value. The application still requires a reviewer decision and deterministic recalculation before it marks the new lines accepted. The old packet stays in the history.
Privacy needs a retention story
An AI accountant may receive identity documents, bank records, wallets, entity agreements, and prior tax returns. The product tells the reviewer which artifacts are temporary and which must survive the filing lifecycle.
At minimum, define:
- who can access the source files and derived claims;
- which model endpoints can receive document text;
- whether tools can make network requests;
- how traces are redacted or exported;
- how deletion handles backups and generated workpapers;
- which approved packet remains available for the taxpayer and advisor.
The AI Agent Sandbox documentation describes the separation between the hosted application, on-chain lifecycle records, and the operator API for live runtime state. That architecture is a design reference. It does not replace the tax product’s own retention and access policy.
Where an AI accountant should stop
An AI accountant should stop, ask, or escalate when:
| Trigger | Required behavior |
|---|---|
| source is missing | name the document and the calculation it blocks |
| source is unreadable | preserve the file and request a better copy |
| sources conflict | show both values and their pages |
| rule version is unclear | hold the draft until a supported rule set is selected |
| a foreign corporation appears | route the ownership and filing questions for review |
| basis cannot be established | keep the gain or loss unresolved |
| a reviewer changes a fact | create a new version and rerun affected calculations |
| a model or tool fails | preserve the partial trace and retry state |
The failure message should help a human recover.
“Foreign corporation mentioned in subscription-agreement.pdf, page 8; ownership percentage and officer status are unconfirmed” is useful.
“International issue detected” gives the reviewer no next step.
The same rule applies to Form 8621, the information return for certain passive foreign investment company shareholders, and to foreign tax credits. The IRS describes the conditions that can require Form 8621 and publishes separate foreign tax credit guidance. The product can identify the questions and attach the sources. It should not infer an election, classification, or credit from a document label.
Pick the product by the packet it leaves behind
Choose an AI accountant for complex tax returns when it leaves an inspectable packet with source pages, calculation inputs, unresolved exceptions, correction history, and approval state. Keep a simpler bookkeeping or filing tool when those source joins do not exist. If the product cannot show that packet, keep its output as an unapproved draft for a qualified reviewer.
What is an AI accountant?
An AI accountant is software that organizes financial records, extracts and links facts, performs controlled calculations, drafts preparation artifacts, and surfaces questions for human review.
Can an AI accountant replace a CPA?
No. It can reduce document and reconciliation work, but taxpayers and qualified professionals still make the final decisions for complex or uncertain positions.
What should an AI accountant produce?
It should produce a source index, claim ledger, calculations, reconciliation report, missing-fact list, draft forms or schedules, and correction history.
How should I review AI accountant output?
Open the source for every high-impact claim, check units and tax year, inspect conflicts and missing records, review changed versions, and confirm the approval state before relying on the draft.
Can Tangle provide the tax answer?
Tangle can provide public infrastructure patterns for a runtime, service definition, operator, payment edge, and recorded run. The tax product still needs its own rules, sources, review controls, and professional escalation.