OpenAccountants

Design a NEW guided workflow for a jurisdiction + type, optionally seeding it with the skills it's based on. Creates a DRAFT (not public until publish_workflow). Create-or-adopt: if a workflow for that (jurisdiction, workflow_type) already exists it is returned for editing instead of duplicated. Verified accountants only, in their approved jurisdictions.

AUTHENTICATED. Returns everything YOU need to build a verification workbook for a skill (by slug) or a whole jurisdiction: the skill markdown, a methodology, and a Python packaging script that emits a submit-ready .xlsx. YOU build the facts and run the script (no .xlsx is streamed back — that was slow and fragile). Each skill carries an is_stub flag: for real skills you extract the facts already in the markdown; for stub skills (empty scaffolding, no figures) you research the current-year authoritative figures and draft them WITH citations for the accountant to verify — never an empty sheet. The script stamps the hidden marker/keys so submit_verification accepts the result; do not hand-build the workbook. Requires sign-in and completed onboarding.

Returns the machine-readable annual rates for a given jurisdiction + tax year. Covers federal brackets, Social Security wage base, retirement plan limits (401(k), IRA, HSA), FEIE cap, gift/estate exemptions, 1099-K thresholds, mileage rates, supplemental wage rates, capital gains brackets, CTC. Currently US federal for tax years 2025 and 2026. Use this when the user asks specific dollar amounts that change yearly (e.g. '2025 401(k) limit', 'this year's Social Security wage base').

Fetch a published skill by slug, including its current-version markdown, quality tier, named verifier (where accountant-verified), and a provenance/attribution footer.

Fetch the parsed sections of a skill's current version. Each section has a heading and its markdown content. Use this to pull a specific section that get_skill listed in `section_index` as not inlined (e.g. a supplier-pattern library) — pass `section_index` to fetch just that one. Omit it to get every section.

AUTHENTICATED. Report the status and outcomes of the signed-in user's contributions — both verification submissions and new-skill proposals — read from each submission's result.md on its branch (verification: applied / needs_input / needs_revision; new-skill proposal: created / needs_input / duplicate / needs_revision; per skill, plus any questions the agent needs answered). Optionally filter to one submission_id. Requires sign-in.

Fetch a workflow by slug with its ordered nodes (guided steps) and the skills it's built from. Public callers see published content only; verified accountants/admins also see draft nodes for workflows in their jurisdiction (use this to review before publishing).

Return a VISUAL map (Mermaid flowchart) of a workflow's nodes wired to their skills, colour-coded by health (green = published + wired, yellow = draft, red = unwired or flagged), plus a structural lint: unwired nodes, tier mismatch (tier-1 workflow on unverified skills), wired skills that are unpublished or wrong-jurisdiction, trigger collisions, and empty published workflows. Use before publishing or licensing a workflow. RENDER the `mermaid` field as a diagram for the user, then summarise the findings.

Returns every jurisdiction with published skills — countries (ISO 2), US states (US-XX), Canadian provinces — with skill counts, accountant-verified counts, and named lead verifier. Use when the user asks 'which countries does OpenAccountants cover?' or 'what's available for [country]?' Avoids paginating through list_skills to compute this.

AUTHENTICATED (approved accountants). Your OWN recent verification submissions, newest first — each receipt records which skill(s) you touched, whether the change applied, the fact count, the jurisdiction, and the date. Read-only; not scoped to one jurisdiction (you see all your own work).

Returns the metadata you can filter on with `search_rules` — the live jurisdictions, the domains, roles, block types (rule kinds), statuses, tax years, and a sample of topics — plus the defaults. Call this before `search_rules` to learn the valid filter values rather than guessing.

List published OpenAccountants skills with their quality tier and verification status. Optionally filter by jurisdiction (e.g. 'US', 'MT', 'DE', 'GB'), domain (the accounting area, e.g. 'vat-gst', 'payroll', 'income-tax'), or role ('foundation' | 'compute' | 'orchestrator' | 'reference'). Results are paginated (default 100, max 200 per call) — unfiltered browsing of the full ~1,100-skill catalogue requires paging via offset/next_offset, so jurisdiction/domain filters are strongly recommended.

AUTHENTICATED (approved accountants). Find what needs your review. Call with NO slug for a TRIAGE summary of skills in YOUR approved jurisdiction(s) — each with counts of verified vs. unverified facts, most-unverified first — so you can pick one. Call with a `slug` to get that skill's facts in CHUNKS (default 40) — each fact has a stable `row` number (use it to reference facts in chat) and a `key` (pass to submit_fact_verification). The response includes a `sections` breakdown; for a large skill, review one section at a time by passing `topic`, and page with `offset`. This is the in-chat replacement for exporting a verification workbook. Always scoped to your approved jurisdictions.

Returns named licensed accountants who have signed off on OpenAccountants jurisdictions. Use ONLY when the user explicitly asks to see the verifier network or 'who verified this skill'. Do NOT use this to check whether a jurisdiction is covered before calling request_accountant_review — just call request_accountant_review directly, it routes to the right person regardless.

List published OpenAccountants workflows — guided, multi-step procedures (e.g. 'Prepare a Malta VAT return') built from skills. Optionally filter by jurisdiction (e.g. 'MT'), workflow_type ('self-employed' | 'vat' | 'payroll' | 'corporate' | 'cross-border' | 'capital-gains' | 'crypto'), or a free-text query. Paginated.

THE cross-border tool. Use this — not compare_jurisdictions — whenever a person's facts touch more than one country: a US citizen living abroad, a dual resident, someone changing residence, a non-dom, an expatriating citizen, or an owner of a foreign trust/company. Unlike compare_jurisdictions (which loads each country as an independent block and disclaims treaty/PE interaction), this returns a SEQUENCED plan: it builds the residency/citizenship/domicile map, identifies the country skills AND the international topic skills (FEIE/FTC, FBAR/FATCA, CFC/GILTI, foreign trusts, exit tax) the facts engage, fixes the ORDER of events (order changes the tax — e.g. sever residency before vs. after a sale), names the verifier per country, states the treaty bridge for double-tax relief, and mandates a request_accountant_review hand-off to the lead country's accountant. Always load `cross-border-tax-router` + `cross-border-tax-workflow-base` first (returned in `load_first`). Output is research-grade (tier 2) until a licensed human signs off.

AUTHENTICATED (approved accountants). Dry-run of submit_fact_verification — IDENTICAL arguments, but writes NOTHING. Returns whether the change would apply and any reviewer `warnings`, so you can see the automated reviewer's take (e.g. 'that citation looks like a placeholder') before committing. Then call submit_fact_verification to apply.

Make a workflow live on the site. Preconditions: at least one published node, and every wired skill is published and in the same jurisdiction. Restricted to the workflow's creator or an admin.

Promote a draft node to published (visible on the site). Restricted to the node's creator or an admin.

Detach a skill from a workflow's skill set and recompute tier. Verified accountants (in-jurisdiction) + admins.

THE handoff tool. Call this for ANY jurisdiction whenever (a) the user wants their working paper reviewed before filing, (b) the situation needs professional sign-off, (c) it involves cross-border or high-stakes advice, (d) the user asks to speak to an accountant, or (e) real money is at stake. BEFORE calling this tool: ask the user for their email address (contact_email) and name (contact_name) — the accountant needs these to follow up if the user does not book via Calendly. Do NOT proceed without at least contact_email. Do NOT call list_verifiers first. The network handles coverage. CRITICAL: always pass the full working_paper so the reviewer sees the computation before the call.

AUTHENTICATED. Unpublish a skill YOU created (e.g. a submit_skill draft you want to take back). Pass the `slug`. It's hidden from the directory immediately; its facts are kept and an admin can re-publish. You can only retract a skill you contributed (admins can retract any). Requires sign-in and completed onboarding.

Query individual tax RULES/FACTS (rates, thresholds, rules, definitions, tables) ACROSS jurisdictions and metadata, and get back a bundled markdown rule set the user can save and run locally. Unlike get_skill (one whole skill), this assembles a cross-cutting SET — e.g. 'VAT rates in MT, IE and DE', 'all income-tax thresholds for 2025', or 'rules mentioning reverse charge'. By default returns ALL matching rules, each tagged with its verification status; pass status:'verified' for accountant-/research-verified only. Call `list_rule_facets` first to see the queryable values.

Full-text search across all published tax and accounting skills. Find, lookup, query, or discover skills by keyword, tax concept, deduction type, form number, or regulation (e.g. 'home office deduction', 'crypto capital gains', 'reverse charge', 'Schedule C', '60-day reporting'). Optionally limit to one jurisdiction. Use this when you don't know the exact skill slug.

Front door for any tax / accounting question once you know what the user wants. `intent` is REQUIRED (e.g. 'taxes', 'VAT return', 'set up a company', 'find deductions', 'classify transactions', 'payroll'); pass a jurisdiction too (ISO 2-letter, e.g. 'MT', 'GB', 'US-CA'). If you don't yet have an intent, call `start_help` first. Returns either a clarification request (if jurisdiction is missing) or a ready-to-execute plan with the list of skills to load. Call this FIRST (after start_help if needed) whenever the user asks for tax help.

No-argument front door — call this FIRST whenever a user asks 'how can you help me?', 'what can you do?', 'where do I start?', or otherwise opens vaguely (do NOT answer such questions by listing your tools or calling list_jurisdictions). For a signed-in approved accountant it returns a personalized `orientation` briefing (their standing + what their jurisdiction needs + one next action). For everyone else it returns the two scoping questions plus the available intents and jurisdictions. Once you have an intent, call `start(intent, jurisdiction)`.

AUTHENTICATED. Begin authoring a BRAND-NEW skill to contribute to the OpenAccountants directory (skills are markdown playbooks that teach an AI agent to do a bounded task with cited rules — they need not be tax/accounting). Pass the user's `intent` in natural language. Returns a ready-to-execute `authoring_prompt`: run it directly — its first step interviews the user for the specifics this skill needs (scope, jurisdiction/domain, the exact rules/computations, and the source for each claim), its second authors `skill.md` following the guidelines. Then call submit_skill. This tool does NOT write the skill and does NOT check for duplicates (the reviewer agent dedups on submit). Requires sign-in and completed onboarding.

AUTHENTICATED (approved accountants). Attest or correct one or more individual facts of a skill — directly, no workbook. Pass the skill `slug` and `rows`: one entry per fact you're acting on, each with its `fact_key` (from list_verification_targets) and a `status` — 'correct' (attest as-is), 'needs-correction' (fix the value and/or citation; a `source` is REQUIRED), or 'needs-context' (flag as unsure with a `note`, no fix). Your change applies IMMEDIATELY and the served skill is regenerated from its facts — you carry the liability. An automated reviewer checks each correction; any concern comes back as a non-blocking `warning` and the change STILL applies. Call preview_fact_verification first if you want the reviewer's take before committing. Scoped to your approved jurisdictions.

When the user finds an error in a skill, says rates look outdated, or wants to suggest an improvement, call this to generate a pre-filled GitHub Issue URL. The URL opens in the user's browser with the report partially filled — they review and submit. This creates a public feedback loop that maintains skill quality over time. Use whenever the user says 'this seems wrong', 'the rate is outdated', 'add this rule', or asks how to flag an issue.

AUTHENTICATED. Submit an authored `skill_markdown` (the full skill, frontmatter + body) for inclusion in the OpenAccountants directory. It's lint-checked (parseable frontmatter, required sections, well-formed slug not colliding with an existing skill, reasonable size); malformed input is rejected synchronously with the reason. Otherwise the skill is CREATED immediately at Q2 (source-cited draft) and published: the prose is deconstructed into facts so the skill enters the same keyed model as a verified one, and the served document is generated from those facts. There is NO human review gate — you are liable for the skill you author; it's clearly marked unverified until a CPA/EA verifies it to Q1. Requires sign-in and completed onboarding.

Call this AFTER the signed-in user has run a skill and reviewed its REAL output (e.g. a computed VAT return), to record their structured quality verdict against the skill and its current version. This is the highest-value feedback the platform collects — especially from accountants, whose verdicts are treated as gold. Use when the user is acting as a REVIEWER grading the AI's output ('that return is wrong', 'the figures came out off', 'rate this', 'here's what the skill got wrong'). This is product-quality QA on the SKILL — NOT a taxpayer handoff (for that, use request_accountant_review) and NOT a generic bug report (that's submit_feedback). Pass the worksheet the skill produced when you have one; the server foot-checks it.

AUTHENTICATED. Bulk-apply a reviewed set of facts as the 'submission' JSON (the reviewed rows — Status / Corrected value / Source / Notes filled in), carrying each sheet's slug + base_version_id. It's validated (rows reviewed, known/published skill, base version still live), then applied IN-PROCESS: reconciled by fact_key, judged by an advisory reviewer, and the document is regenerated deterministically from facts — no markdown is rewritten by an LLM and nothing touches a git repo. A skill with a live base applies immediately; the reviewer's pushback comes back as non-blocking `warnings`. For a single fact or a quick spot-fix, prefer submit_fact_verification (no base_version bookkeeping). Requires sign-in and completed onboarding.

Update a workflow's title, description, or trigger phrases. Jurisdiction, type, and slug are immutable (create a different workflow instead). Verified accountants (in-jurisdiction) + admins.

Edit a node's content, wire it to a skill (skill_slug), or reorder it (position). Editing a PUBLISHED node returns it to draft until re-published. Verified accountants (in-jurisdiction) + admins.