MCP server & tools

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)`.

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.

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 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.

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.

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.

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').

Quick SIDE-BY-SIDE loader. Loads the income-tax skills for 2–5 jurisdictions as independent blocks so the agent can produce a static comparison (effective rates at a given income level, headline differences, entity-choice implications). It does NOT sequence events or bridge treaties. Use for 'should I incorporate in X or Y?', 'compare tax in MT vs IE', or any standalone side-by-side. NOTE: if the person's facts actually INTERACT across borders (a US person abroad, a residence change, a foreign trust/company, an expatriation), use `plan_cross_border` instead — that tool returns a sequenced plan and the treaty bridge this one deliberately leaves out. The two are siblings: this one for static compares, plan_cross_border for live cross-border planning.

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.

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.

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.

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.

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.

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.

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.

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.

Attach a published skill (same jurisdiction) to a workflow's ordered skill set. Recomputes the workflow tier. Verified accountants (in-jurisdiction) + admins.

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

Add a guided step (node) to a workflow. Creates a DRAFT node. Optionally wire it to the skill that performs its computation (skill_slug). 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.

Soft-delete a node. Refused if it would leave a published workflow with no published nodes. Verified accountants (in-jurisdiction) + admins.

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

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.

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.

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. 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.

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.

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.

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.

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.

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.

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.

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).