Tool reference
Every tool, from the live surface
51 tools, generated from the deployed catalog (surface 62644355c35b). Descriptions are the same text your AI reads over MCP — including whether each tool is read-only and whether it is metered.
Workspace and intake
Create the workspace, turn sources into Standard Documents, submit the accounting basis.
Create workspaceidempotent
create_workspaceCreate the workspace that scopes admitted documents, shared reality, optional charts, review work, and reports. The authenticated caller becomes its owner; metered work in it bills that owner. Creation does not assert an accounting entity and does not admit documents. A workspace with statements and no chart is a complete outcome. Idempotent by owner plus exact active name: a retry returns the existing workspace as workspace_reused. Persist workspace_tag; the name is not a unique id. Next: gather source documents, create_standard_statements, then submit. Durable mutation; not metered.
List Workspacesread-onlyidempotent
list_workspacesList active workspaces owned by the current principal, newest first. Use it to recover a workspace_tag when none is in hand. Optional name is an exact match after trim — the same key as create_workspace reuse. An empty page is a successful list, not an error. Read-only, paginated, and not metered.
Create Standard Statementsidempotentopen-world
create_standard_statementsRetain one exact financial source and create its complete ordered set of Standard Statements as one durable FinStat Task. Supply exactly one byte-bearing source: an authorized handle or bounded content_base64. The transfer program is the reliable intake: create_upload_sessions, PUT the bytes, pass the returned handle. Inline content_base64 is for small sources only — many MCP clients cap tool arguments in the tens of KB regardless of this schema's bound; if an inline call fails to leave your client, switch to the transfer program rather than shrinking the source. PDF is the normal case; canonical statement JSON bytes are accepted (exact-byte, no model). One source may yield several Standard Statements. Persist taskId. Native clients poll tasks/get; ordinary clients poll tasks_get. Completion returns fresh expiring handles. The source bytes remain unchanged and are not returned. Exact-byte replay recovers the existing creation without another interpretation charge. Nothing is admitted. Metered only when new interpretation runs.
Validate and submit Standard Documentsdestructive
submitAdmit one atomic batch containing only FinStat Standard Statements, Standard Charts, or Standard Declarations, then settle it as one durable FinStat Task. FinStat validates every item and the whole batch before admitting anything. One invalid item rejects the batch with item-specific repair information, commits nothing, and creates no Task. A returned taskId proves admission, not settlement; persist it and poll tasks_get at pollIntervalMs. Task complete waits for this admission's request jobs and the workspace event-derivation and chart-posting walks they start. wait_for_workspace_idle remains the workspace-wide doorbell when other work may still be running. A retry is a new admission against current workspace state — already-admitted or duplicate documents are refused. Lost taskId: list_submissions. Bare Canonical Statements and unrecognized kinds are refused. Not metered.
List source documentsread-onlyidempotent
list_source_documentsList source provenance admitted to one workspace. These are the workspace's source documents, not every source artifact retained by Standard creation. Each row reports immutable source identity, whether original bytes are still retained, and the statements admitted from it. Download retained bytes with create_download_sessions and source_document_id. A portable Standard Statement admitted without original bytes may appear with bytes_available: false; that is truthful and does not block the statement. Read-only and not metered.
List statementsread-onlyidempotent
list_statementsList typed statements admitted to one workspace. Each summary reports its durable semantic key, source lineage, form, type, period, currency, printed parties and accounts where applicable, reconciliation verdict, and row or detail count. A statement is evidence about the world, not a source file and not a journal entry. Type is one of the fourteen catalog keys. Read-only and not metered.
List recent submissionsread-onlyidempotent
list_submissionsList this principal's durable submission Tasks in one workspace, newest first. submit is not idempotent; use this to recover a lost taskId after disconnect, timeout, or restart. It does not list create_standard_statements Tasks — those are recovered through list_transfer_sessions. Rows are bounded summaries; the complete receipt is tasks/get or tasks_get. The MCP Tasks extension has no tasks/list. Read-only and not metered.
Standard Documents
Sealed, portable, tamper-evident — verify, open, render, export, author.
Verify Standard Documentread-onlyidempotent
verify_standard_documentAuthenticate and validate one Standard Statement, Standard Chart, or Standard Declaration without returning its canonical body. Supply exactly one authorized transfer handle. FinStat identifies the species, verifies its authenticity and content identity, re-derives required laws, and returns bounded routing and identity facts. It does not admit the document. Use open_standard_document when the reviewable body is needed. Read-only and not metered.
Open Standard Documentread-onlyidempotent
open_standard_documentAuthenticate one Standard Document and return its complete equivalent canonical content for review. A Standard Statement opens to canonical statement JSON; a Standard Chart or Declaration opens to its clear canonical document. Supply exactly one authorized transfer handle. Large canonical content is staged behind a fresh download handle rather than truncated. Opening does not repeat interpretation, admit anything, or change workspace financial state. Read-only and not metered.
Render Standard Statement
render_standard_statementRender exactly one authenticated Standard Statement as a newly generated human-readable presentation PDF. Supply exactly one authorized transfer handle. The output is retained behind a download handle. Rendering admits nothing and changes no workspace financial state. Not metered.
Export Standard Statement
export_standard_statementConvert one authenticated Standard Statement into one interchange file. Provide exactly one authorized transfer handle and the closed format: qbo (one QuickBooks Web Connect file), ofx (one generic OFX file), or csv (one CSV file). When format is csv, also provide target from the closed column contract quickbooks, xero, sage, or finstat. The export preserves the statement's account identity, dates, currency, and statement-side signed amount meaning. It authenticates the handle through the same membrane as open_standard_document. It does not admit the statement, require prior admission, or read or change workspace books. The result is an expiring download handle with format, size, and SHA-256. A multi-statement or non-statement Standard Document is rejected. Not metered.
Validate Standard Chartread-onlyidempotent
validate_standard_chartVerify one Standard Chart without installing it and without calling a model. Supply exactly one inline chart candidate or authorized UTF-8 handle. FinStat checks the chart_of_accounts discriminator and version, closed schema, hierarchy and claim invariants, canonical content hash, and FinStat seal. A malformed, edited, unsealed, or foreign-sealed document returns chart_invalid as a normal verdict. Removing contentHash does not repair a broken seal; re-author and reseal changed content. Read-only and not metered.
Create Standard Chartopen-worldmetered
create_standard_chartAuthor one sealed Standard Chart from supplied chart source — CSV, an outline, notes, rough Markdown, or rough JSON. Supply exactly one of inline text or a retained UTF-8 handle. FinStat gives the model the workspace's observed account designators as context, then validates the result with the same chart_of_accounts schema and admission invariants used by submit, computes its canonical content hash, and seals it. It does not install a chart and does not mint a party. owner is a read: the mention plus whether submit will reuse a live party or found one. Review the returned Standard Chart with open_standard_document or validate_standard_chart and submit it when ready. The advisory filename is .chart.json. Model-backed and metered; one bounded authoring pass.
Get declarationread-onlyidempotent
get_declarationReturn one authorized declaration's complete canonical body plus its admission and application history. Select by local declaration_id or portable content_hash. Kind is one of the six authorable kinds. Leftover kinds are object_unavailable, not a historical body. Read-only and not metered.
List declarationsread-onlyidempotent
list_declarationsList admitted Standard Declarations and their separate admission and application states. Filter by scope, kind, application state, author, or content hash. Results include attribution, durable references, pending or refusal reason, and applied revision without embedding full bodies. Kind is one of the six authorable kinds. coa_retirement, statement_note, and adjustment_schedule are refused. Read-only and not metered.
Shared reality
What the evidence established: parties, accounts, events, activity.
List partiesread-onlyidempotent
list_partiesList parties known in shared workspace reality: canonical name, type, aliases, owning-account count, provenance grade, and permanent merge target. A party is not a chart entity opinion. party_type is individual, business, trust, nonprofit, government, or unknown — not person. Read-only and not metered.
List workspace accountsread-onlyidempotent
list_workspace_accountsList every live account endpoint in a workspace: statement-backed instruments, owned or external counterparties, and explicit unidentified endpoints. Each account reports workspace_account_id, type, display identity, currency, followed owner and fiduciary parties when known, merge target, register activity, and per-chart claims and bindings. Owner is whose instrument; fiduciary is who holds or issues it. No singular chart binding is implied. This is shared reality, not list_chart_accounts. Read-only and not metered.
List workspace account activityread-onlyidempotent
list_workspace_account_activityList one account's side of each movement. Select exactly one account by workspace_account_id or exact live workspace_account_identifier. The same movement can appear for both endpoint accounts with opposite signed amounts; each side may name its containing event. Filter by inclusive dates and page in deterministic order. These are not register rows and not journal entries. An omitted account selector is invalid_arguments. Read-only and not metered.
List eventsread-onlyidempotent
list_eventsList the events derived from admitted evidence. An event is one equivalence class of movements or claims, not a mutable container and not an event group. Each row reports its stable semantic identity, kind, amount and currency where applicable, disambiguating date, member evidence, lifecycle, and per-chart posting outcome. Read-only and not metered.
List review itemsread-onlyidempotent
list_review_itemsList durable FinStat findings that may require human review in this workspace. Supply workspace_tag only. Each item states what was detected. An empty result means no matching finding is visible; it is not assurance that the books are correct. A workspace-wide posting pause appears as posting_held while it is in effect. Read-only and not metered.
Resolve or prepare resolution for review items
resolve_review_itemsAct on one or more current review findings using only their closed choices. Each decision names a review_item_id from list_review_items and one of its listed choice_ids. Today the only closed choice is dismiss (chart-posting attention items): it records the actor and reason on the review row and closes the item. Findings that state a missing fact — an unidentified endpoint, an unposted opening balance — carry no choices; they resolve when the fact they name is fixed (an identity answer, an admitted document), and a decision naming them returns outcome not_resolvable_here. Durable review mutation; not metered. Not a Task.
Workspace overviewread-onlyidempotent
workspace_overviewReturn one current snapshot of a workspace: identity, admitted documents and statements by form, parties, workspace accounts, events, charts, declarations, journal entries, public Tasks still working, internal processing effects, open review items, whether processing is idle, and whether chart posting is paused. Counts are facts, not a plan. It does not wake workers and does not imply correctness. Requires workspace_tag. Read-only and not metered.
Charts and reports
A chart is a model; the books are a projection onto it.
List chartsread-onlyidempotent
list_chartsList the workspace's active and optionally retired charts. Several charts may coexist, each asserting one entity, accounting basis, and classification policy over shared events. Every row exposes chart_id. There is no coa_id. entity.name is the stored mention; entity.party_id and entity.display are the followed workspace party, or null while none answers. owner_unresolved is true and warning is set while no party answers — that chart writes no passed reviews; events stay pending. owner_disagreement_count is bound instruments whose followed owner is not that party. A workspace-wide posting pause from pause_all_chart_posting appears on every active chart as the same posting object. Read-only and not metered.
List chart accountsread-onlyidempotent
list_chart_accountsList account definitions and current currency-partitioned balances for one chart, or for every active chart when chart_id is omitted. Each row reports chart_id, code, name, kind, policy description, hierarchy, derived summary/leaf state, aliases, claims, and balances. Summary accounts are identifiable and never take postings or claims. An unknown chart_id is an error, not a widened query. Read-only and not metered.
Generate balance sheetread-onlyidempotent
generate_balance_sheetGenerate a balance sheet for one chart_id through an optional inclusive as_of_date. chart_id is required when the workspace has more than one active chart and may be omitted when exactly one exists. Assets, liabilities, and equity are returned by chart account, with rollups and totals, separately for each currency. Unlike currencies are never summed. A deficit or abnormal natural-side balance remains signed; FinStat does not force it positive. The equation is Assets = Liabilities + Equity. A posting pause is a caution, not a refusal. Read-only and not metered.
Generate profit and lossread-onlyidempotent
generate_profit_and_lossGenerate a profit-and-loss statement for one chart_id over an optional inclusive date range. chart_id is required when the workspace has more than one active chart and may be omitted when exactly one exists. Omitted bounds are open-ended. Revenue, expenses, and net income are returned separately for each currency with chart-account rollups. Unlike currencies are never summed. A posting pause is a caution, not a refusal. Read-only and not metered.
Generate trial balanceread-onlyidempotent
generate_trial_balanceGenerate a trial balance for one chart_id through an optional inclusive as_of_date. chart_id is required when the workspace has more than one active chart and may be omitted when exactly one exists. For each currency, return chart-account debit and credit balances, totals, difference, and balance verdict. Unlike currencies are never combined. The check is Assets + Expenses = Liabilities + Equity + Revenue. A posting pause is a caution, not a refusal. Read-only and not metered.
Generate workspace reportread-onlyidempotent
generate_reportGenerate one current-state generic workspace report selected from list_report_options. The six catalog views are workspace-wide; the filters object is accepted for compatibility and is not applied. Use generate_balance_sheet, generate_profit_and_loss, and generate_trial_balance for chart-scoped financial statements. Read-only and not metered.
List report optionsread-onlyidempotent
list_report_optionsReturn every generic report_type accepted by generate_report, with its title, meaning, row columns, and exact supported filters (none today: the six catalog views are workspace-wide and unfiltered). The catalog is the same closed registry generate_report dispatches on. Generic MCP reports are JSON. Financial statements use their dedicated tools and their own parameters. Read-only and not metered.
Pause all chart posting
pause_all_chart_postingPause automatic posting on every active chart in the workspace so documents can be admitted and reviewed before any chart books. Admission, shared-reality resolution, and event derivation continue. This is not a closed period and does not lock dates. Holding requires a reason. resume_after is the latest the pause may last (minutes, inclusive bounds); it is a safety deadline, not the signal that QA is finished. Calling pause again while already paused resets the deadline. Overview and reports must show that posting is paused and when it will resume. A restore from portable Standard Documents starts un-paused. Operational state, excluded from the semantic books digest. Durable operational mutation; not metered.
Resume all chart posting
resume_all_chart_postingEnd a workspace posting pause now and schedule eligible deferred chart projection. Use this when batch load and QA are finished; do not wait for resumes_at unless the session is gone. If no pause is in effect, return the current released state without scheduling a second grind. Operational state, not financial evidence. Durable operational mutation; not metered.
Transfers
Byte-exact intake and delivery through signed, expiring programs.
Create upload sessionsidempotentopen-world
create_upload_sessionsCreate bounded, expiring upload programs for one or more files the host holds. One item is one file. Exact replay of the required idempotency_key returns the same sessions and signed PUT programs; reuse with changed inputs is idempotency_conflict. After PUT, FinStat checks declared size and optional SHA-256 and retains the exact bytes behind the handle. It does not inspect or interpret them. Uploading does not admit a document and does not author a Standard Document. Not metered.
Create download sessionsidempotentopen-world
create_download_sessionsCreate single-use, expiring download programs for one or more authorized immutable artifacts. Each item names exactly one subject: a retained handle or an admitted source_document_id. Exact replay of the required idempotency_key returns the same sessions and programs. Bytes are never returned inline. Verify every GET against the returned SHA-256. After a failed or consumed GET, mint a new session; do not retry the signed URL. Reminting does not mutate the artifact. Not metered.
List transfer sessionsread-onlyidempotent
list_transfer_sessionsList or recover authorized upload and download sessions for one workspace, newest first. Filter by session identity, direction, or state. Use this after a timeout before repeating transfer creation or metered production. A ready Standard Document handle feeds verify_standard_document, open_standard_document, and submit. Listing does not transfer bytes, expose signed programs, consume a program, extend retention, repeat processing, or change books. Read-only and not metered.
Check data channelidempotentopen-world
check_data_channelProve whether the current host can execute FinStat's signed HTTPS upload program. Start with workspace_tag and idempotency_key; exact replay returns the same short-lived nonce, opaque check_id, and PUT program. The host executes that program with the exact nonce, then calls again with check_id. FinStat returns pending while proof may still arrive, capable after verification, or incapable only after expiry without proof. Transfer-service failure is data_channel_unavailable, not incapable. The probe is never admitted. Temporary state only; not metered.
Tasks and processing
Durable work, bounded waits, honest processing summaries.
Get FinStat Taskread-onlyidempotent
tasks_getReturn the current state of a durable FinStat Task without waiting. Use the taskId from an accepted submit or create_standard_statements. Ordinary clients call this tool because they have no tasks/get method. A completed submission includes its receipt; completed Standard creation includes fresh expiring Standard Statement handles. Persist taskId; it survives disconnects and does not expire independently of the workspace. Ordinary profile only. Read-only and not metered.
Wait for workspace processing to become idleread-onlyidempotent
wait_for_workspace_idleWait until one workspace has no active internal processing effects, or until timeout_seconds elapses. This is a workspace-wide doorbell after one or more Tasks; it is not Task polling and does not prove that any particular submission succeeded. Another caller's work can keep the workspace busy. A posting pause can make the workspace idle with unposted chart work. A timeout is a normal result — default 300 seconds, maximum 300. Hosts with shorter tool-call windows may request a smaller timeout or poll tasks_get. The tool only observes — it never wakes workers, sends notifications, or changes advisory state. Both profiles. Read-only and not metered.
Guides, examples, and service
The engine documents itself to your AI.
Get startedread-onlyidempotent
get_startedReturn the FinStat workflow: create or recover a workspace, turn source PDFs into Standard Documents, keep those files locally, submit them as the accounting basis, use the workspace without a chart, optionally install charts as projections, and share documents across a group so any FinStat system can reproduce the books. Transfer sessions move file bytes; a handle from a session or a producing tool is passed straight to the next tool — do not download and re-upload. The guide is the same every time. If workspace_tag is supplied and authorized, callable steps include it; missing host values stay host steps, never placeholder calls. Charts are optional. Pause posting is a batch-load option, not a default next step. Read-only and not metered.
Guide to FinStat vocabularyread-onlyidempotent
guide_glossaryReturn the authoritative FinStat glossary. Standard means the FinStat Standard — a sealed, portable, tamper-evident document — not GAAP, not IFRS, not a generic or ISO form. The pack defines document, statement, declaration, and chart; the three statement forms and fourteen types; the double-entry equation; GAAP (FASB) and IFRS (IASB / EU endorsement) as outside books-policy authorities; interchange formats QuickBooks, QBO, OFX, CSV, Xero, and Sage; and shared reality versus a chart. Optional terms selects a subset, including a statement type key (checking, invoice, …) which returns that type's form. Omit for the full pack. Retired words are listed so hosts do not reuse them. Read-only, no workspace, and not metered.
Guide to FinStat Tasksread-onlyidempotent
guide_tasksReturn the FinStat Task guide: the official MCP Tasks extension io.modelcontextprotocol/tasks (SEP-2663), the ordinary-client parallel for hosts that do not advertise that extension, the submit / create_standard_statements workflow, and optional pause_all_chart_posting / resume_all_chart_posting. The guide is the same every time. It cites the published MCP specification and SEP. FinStat may use those official documents as teaching material for the native profile. The ordinary tasks_get poll is FinStat's and is not in the extension. Read-only, no workspace, and not metered.
Guide to canonical schemasread-onlyidempotent
guide_canonical_schemaReturn the exact machine schema the current parser and encoder accept for one canonical species: statement (default), chart, or authorable declaration. The schema is closed and drift-tested against the owning xw-standard-* package. Laws JSON Schema cannot express are listed in authoring_notes. Historical non-authorable declaration kinds are not in the authoring schema. Read-only, no workspace, and not metered.
Guide example-case constructionread-onlyidempotent
guide_example_caseReturn a host playbook for building a coherent example from a user's real source documents. FinStat does not invent evidence. The playbook covers a scratch workspace, a coherent source set, Task-backed Standard Statement creation, polling the Task with tasks_get or tasks/get, atomic submit, then workspace_overview. A chart is optional and uses create_standard_chart. If workspace_tag is supplied, the guide uses it and does not create an unused workspace. Every tool step has schema-valid arguments; missing host values are host actions, not placeholder calls. Read-only and not metered.
Example cases
example_casesList or deliver curated synthetic example bundles without creating a graded test. Call with no arguments for the catalog. Supply case_key and workspace_tag to mint download sessions for that frozen bundle. Bundles may contain source files, Standard Statements, Standard Charts, Standard Declarations, and instructions. They never contain coa.md. Downloading admits nothing and does not seed the workspace books. For an isolated scored workflow, use case_test. Not metered.
Run case test
case_testCall with no arguments to list the frozen built-in case catalog. Start one case with case_key; FinStat creates and binds a disposable isolated workspace, freezes the case version, and returns its declared artifacts plus a schema-valid ordered runbook. Call later with test_id to remint expired download sessions without changing the case or workspace. Follow the runbook and call grade_case_test. The bundle contains no real customer data or COA Markdown. Starting mutates isolated test state. Catalog and remint are not metered. Start may be metered when the case requires interpretation.
Grade case test
grade_case_testGrade the disposable workspace already bound to test_id against that test's frozen expectations. FinStat checks admitted source documents, statements, parties, accounts, events, review findings, charts, declarations, journal entries, trial balance, and artifact integrity. Optional uploaded copies are compared only; they are never submitted or admitted. Omitted copies yield skipped integrity checks, not failures. Re-run after correcting the workspace. The grade writes only test audit history. Not metered.
Inspect MCP connectionread-onlyidempotent
inspect_mcp_connectionReport what the server observes on this request: client name and version when supplied, User-Agent as a displayed string, resolved protocol revision and which slot claimed it, whether this client advertised the Tasks extension, authorization shape without the credential, transport, and whether a stale Mcp-Session-Id was sent (ignored; this server is sessionless). The banner is the paste-ready card: it cites MCP specification 2026-07-28 and, when this build implements it, the official Tasks extension io.modelcontextprotocol/tasks (SEP-2663), then the facts of this request. Request history is included only when a partition is securely bound to the authenticated principal and this client instance; otherwise history.available is false. A shared User-Agent is never a client identity and never a history key. Read-only, no workspace, and not metered.
Service statusread-onlyidempotent
service_statusReturn this service's build identity, protocol posture, component and migration health, and the current public-surface hash. No workspace. Call at startup and retain surface.surface_hash. surface.announced_surface_hash pins that descriptor hash to the newest curated release note and must match. If a later result — this tool or any other — carries a different hash or a surface_notice, discard the cached catalog and call tools/list again. Echo the retained hash on later calls as _meta["ai.finstat/surface-hash"] for a precise stale/current answer. recent_changes is the current window only, in current public names. status is healthy or degraded; degraded is a successful result, not a failed call. Read-only and not metered.
Other
Decode QuickBooks Online exportmetered
decode_qbo_exportDecode one completed upload of a supported QuickBooks Online export into portable Standard Documents: one Standard Statement per reconstructed account, a Standard Chart only when the export supplies the facts required to assert it, and a parties Standard Declaration when source-backed parties exist. Every artifact is a transfer handle for verify_standard_document, open_standard_document, and later submit. The archival decode report has its own handle and is not a submit input. Nothing is admitted. The upload session is consumed. A later decode needs a new upload and runs again; it does not replay. Metered when model interpretation runs.
Get workspace processing summaryread-onlyidempotent
get_workspace_job_summaryReturn a non-blocking workspace-wide summary of internal processing effects by public domain and state. enqueued and processing are current-state counts, not lifetime totals; completed is how many effects have finished. It reports unresolved failures and the public Tasks that can be inspected. It never exposes job ids, attempts, worker names, queues, providers, or retry topology. The read does not wake workers. Use tasks_get / tasks/get for one public Task, or wait_for_workspace_idle for a bounded workspace barrier. Read-only and not metered.
Create chart-scoped Standard Declarationopen-worldmetered
create_standard_declaration_chartAuthor one sealed declaration whose meaning belongs to exactly one chart. Select the chart by chart_id. Choose journal_entry, journal_entry_void, or retirement, and describe the accountable assertion in ordinary language. FinStat supplies that chart's account policy to the model and validates the returned declaration with the exact parser used by submit, including dates, balance, references, attribution, and chart account codes. It changes no books; review and submit the returned document. Model-backed and metered.
Create workspace-scoped Standard Declarationopen-worldmetered
create_standard_declaration_workspaceAuthor one sealed declaration that is true in shared workspace reality and names no chart. Choose account_identity, parties, or workspace_correction and describe the accountable assertion. One account_identity identifies one account; one parties declaration may assert a set of parties and aliases. Canonical partyType values are individual, business, trust, nonprofit, government, or unknown. FinStat validates the returned document with the parser used by submit. It changes no books; review and submit it. The advisory filename is .declaration.json. Model-backed and metered.