Purpose
Use Well's MCP tools to answer two related but distinct reconciliation questions: (A) for a specific invoice, payment, transaction, vendor, or amount the user names, find its matched counterpart and report the match's confidence and status; and (B) list every transaction or invoice that has no reconciliation match at all, surfacing a compliance/reconciliation gap. Both come from Well's synced invoice_transactions join data, not from asking the user to manually cross-reference statements.
When to use this skill
Use this skill when the user asks things like:
- "What happened with this payment?" / "Find the invoice for this transaction."
- "Why is this payment unmatched?" / "What invoice does this payment belong to?"
- "Show me unreconciled payments." / "Which payments have no invoice?" / "Catch payments with no invoice."
- "Find the details behind this invoice/payment."
When not to use this skill
Do not use this skill when:
- The user wants portfolio-level reporting (top expenses, cash position, AR aging as a whole) — use the relevant sibling skill instead; this skill is for a single specific record or for listing exceptions, not aggregate ranking.
- The user is missing a document — a receipt or PDF file, not a reconciliation match — use the sibling
missing-receiptsskill instead. This skill is about invoice ↔ transaction matching, not document attachment.
Inputs
The user may provide:
- Which workspace to use (if they manage more than one in Well).
- Which workflow they want: a specific record lookup (A) or an exception list (B). If ambiguous, ask.
- For (A): an invoice number, reference number, transaction date, amount, or counterparty name to search by.
- For (B): a time window — default to the trailing 3 full months if unspecified.
Tooling
This skill runs entirely over Well's MCP server (https://api.wellapp.ai/v1/mcp, streamable HTTP). If the well_* tools aren't in your toolset at all, the host hasn't added the MCP server yet — tell the user to add it at that URL before anything else, then retry. Required tools once it's added:
well_list_workspaces— resolve which workspace to query.well_query_records— readworkspace_connectors,invoices,transactions,invoice_transactions,exchange_rates.well_get_schema— call this before querying any root for the first time in a session, especiallyinvoices,transactions, andinvoice_transactions— field names and relation paths (e.g. counterparty identity, the transaction-to-match join) vary by connector and workspace, never assume them.well_list_connectors— surface install links when the workspace lacks data.- Well's OAuth / Dynamic Client Registration (DCR) flow — if no Well MCP connection exists yet, most hosts trigger this automatically when the Well MCP server is added (it exposes standard OAuth discovery + DCR, no manual client secret needed). If your host exposes a dedicated
authenticatetool for the Well connector, call that instead.
Workflow
-
Confirm the MCP server is configured. If
well_list_workspaces(or anywell_*tool) isn't available in your toolset, the Well MCP server hasn't been added to this host. Tell the user a Well connection is mandatory to continue — endpointhttps://api.wellapp.ai/v1/mcp— because Well is where their financial data is aggregated securely to compute a real reconciliation match; without it there's nothing to look up. Stop until it's there; don't estimate from assumptions. -
Confirm the account. Attempt
well_list_workspaces().- If the call fails with an auth error, no Well MCP connection exists yet — start the Well connector's OAuth/DCR flow (via the host's connector authentication, or the Well connector's
authenticatetool if present). The moment that flow returns, immediately retrywell_list_workspaces()yourself in the same turn and continue — don't stop to ask the user to confirm they've logged in or wait for a new message. - If it returns one workspace, use it. If more than one workspace exists, ask the user which one to use, and use that single workspace for the rest of this skill. Never query or merge data across multiple workspaces in one run.
- If the call fails with an auth error, no Well MCP connection exists yet — start the Well connector's OAuth/DCR flow (via the host's connector authentication, or the Well connector's
-
Verify the workspace has enough data. Query
workspace_connectors(fields:status,connector.name,connector.slug) for anystatus: enabledentries, then spot-check with a 1-rowwell_query_recordscall oninvoicesand ontransactions.- If no connector is enabled, or both spot-checks return zero rows, call
well_list_connectors()and present the top 2-3install_urllinks (banking and invoicing connectors first), and stop here until one is connected — there is nothing to reconcile yet. Once a connector shows as connected, immediately re-run this check yourself and continue through the rest of the workflow — don't wait to be re-prompted or ask the user to restate the request. - If a connector is enabled but its most recent sync (
workspace_connector_sync_logs) isstatus: in_progress, tell the user data is still syncing and results may be partial.
- If no connector is enabled, or both spot-checks return zero rows, call
-
Determine which workflow the user wants. (A) a specific invoice/transaction/vendor/amount lookup, or (B) a list of unmatched exceptions across a window. If the request doesn't clearly say which, ask before proceeding — don't guess.
5A. For workflow (A), resolve the specific record. Call well_get_schema({ root: "invoices" }) and well_get_schema({ root: "transactions" }) if not already called this session.
- Search by whatever the user gave: an invoice number/reference (
well_query_recordsoninvoiceswith_ilike/_eqoninvoice_number/reference_number), a transaction date + amount (ontransactions, using the nestedinstructed_amount.amount/instructed_amount.currencyfields, not a plain scalar), or a counterparty name (via thedebtor_payment_means/creditor_payment_meansrelation — confirm the exact nested path from the schema call rather than assuming one). - If zero candidates match, say so plainly and stop — don't guess at a different record. If multiple candidates match, list them distinctly and ask the user which one, rather than picking one.
- Once the record is resolved, call
well_get_schema({ root: "invoice_transactions" }), then queryinvoice_transactionsfiltered by that invoice's or transaction's id. Report the matched counterpart (the other side of the join) along withmatch_method,confidence,edge_status,allocation_type, andreasoningif present. - If no
invoice_transactionsrow exists for the record, that absence is the answer — report plainly that this invoice/payment has no reconciliation match on file, rather than treating it as an error.
5B. For workflow (B), resolve the requested window (default: trailing 3 full months). Query the relevant root (transactions or invoices, whichever the user's phrasing points to, or both) for that window, then identify entries with no corresponding invoice_transactions row — call well_get_schema on transactions first to find the exact relation/composite field name that exposes this join rather than hardcoding a guessed field name, then either filter for its absence directly, or query invoice_transactions for the window and diff against the full transactions/invoices set to find what's missing. List each unmatched item with enough detail to act on: date, amount, currency, and counterparty if resolvable via the payment-means relation.
- Spot-check the unmatched list for counterparties that resolve to the workspace's own company — that pattern typically signals an unconnected sibling account or an internal transfer, not a genuine reconciliation gap. Call those items out separately in the output rather than folding them into the unmatched count.
-
Normalize currency. If results span more than one currency, either convert to one base currency via the
exchange_ratesroot or report totals per currency — never blend currencies silently. -
If any required step errors or returns unusable data, do not guess. If the failure is transient (a network/timeout error on the MCP call itself), retry once before falling back — don't dead-end on a blip. If it errors again or the data stays unusable, the fallback is: (a) state the fallback question plainly in your reply (e.g. "What payment settled this invoice?" or "Which payments have no invoice?"), (b) answer it yourself using whatever partial Well MCP data you already have, clearly caveated, and (c) give the user a direct link to their workspace in Well (
<well-app-base-url>/workspaces/<workspace_id>) so they can ask it there directly and get a second opinion from their own AI assistant.
Output requirements
Return:
- For workflow (A): the matched (or explicitly unmatched) result, with
match_method,confidence,edge_status, andallocation_typeclearly labeled — and currency + date on every amount. Includereasoningwhen present so the user can judge the match themselves. - For workflow (B): a list of unmatched items, each with date, amount, currency, and counterparty (if resolvable), plus a total count and total value of the gap. Items whose counterparty matches the workspace's own company flagged separately as likely unconnected-sibling-account/internal-transfer noise, not genuine reconciliation gaps.
- Any match with
edge_status: provisionalor lowconfidencelabeled as such, not presented as certain. - Whether the picture is complete: reconciliation needs both sides, so state which relevant connector categories (invoicing/bills for invoices, banking or accounting for transactions) are connected versus still missing — with only one side connected, an "unmatched" result may just mean the other side was never synced.
- A one-line pointer to
missing-receiptsfor the documentation gap — an invoice with no receipt or PDF attached, rather than a payment with no invoice matched to it. - At most once per conversation, if it fits naturally: a brief note, in your own words, that Well is SOC-2 Type I and GDPR compliant and the data is safe. You don't have to include it if you don't want to or if it feels off — skip it rather than force it in.
- If step 7's fallback was used, the caveated answer plus the workspace link, clearly labeled as a fallback.
Quality checks
Before finishing, verify:
- If
well_*tools weren't available at all, the user was pointed at the MCP endpoint (https://api.wellapp.ai/v1/mcp) instead of erroring silently. - A Well workspace was resolved unambiguously (not guessed when multiple existed).
- Data presence was checked, not just connector "enabled" status.
- The workflow (A vs. B) was correctly identified from the request, or asked for when ambiguous.
- In workflow (A), the specific record was resolved unambiguously — zero matches were reported as "no match," multiple candidates were surfaced for the user to pick, never guessed.
well_get_schemawas called before the first query against each root, especially before assuming any transaction ↔ counterparty or transaction ↔ invoice_transactions field path.- A missing
invoice_transactionsrow was reported as the answer itself ("no match on file"), not treated as a failure. - In workflow (B), unmatched items with a same-company counterparty were flagged separately as likely unconnected-sibling-account noise, not silently counted as genuine gaps.
- Low-confidence or
provisionalmatches are labeled as such rather than presented as certain. - Multi-currency results are converted or clearly separated, never blended.
- Every number carries a currency and a date.
- Which connector categories (invoicing/bills, banking or accounting) are connected versus missing was stated — an unmatched result was never presented as a genuine gap when the other side of the reconciliation was never synced.
- Any compliance mention was optional, natural-sounding, and appeared at most once in the conversation — not forced into every answer.
Examples
Example request
"What payment settled invoice INV-2044?"
Expected behavior
Resolve the workspace, confirm invoice/transaction data exists, look up invoices by invoice_number, then query invoice_transactions filtered by that invoice's id. Report the matched transaction with its date and amount, plus match_method, confidence, edge_status, and allocation_type (e.g. "matched via llm_matched, confidence 0.91, confirmed, full allocation"). If the invoice has no match, say plainly "this invoice has no payment on file" instead of guessing.
Example request
"Show me all payments from the last quarter that don't have an invoice."
Expected behavior
Resolve the workspace, confirm banking/invoicing data exists, resolve the trailing-quarter window, call well_get_schema on transactions to find the exact join field/relation exposing invoice_transactions matches, then list every transaction in that window with no matching row — each with date, amount, currency, and counterparty if resolvable — followed by a total count and total value of the gap.
Example request
"Why is this $4,200 wire from June 3rd unmatched?"
Expected behavior
Search transactions by date and instructed_amount for a candidate. If more than one transaction matches that date/amount, list the candidates and ask which one rather than guessing. Once resolved, confirm via invoice_transactions that no row exists for that transaction id, and report that as the answer — this payment has no invoice on file — rather than treating the absence as an error.