Look Up Payment ↔ Invoice Matches with Well

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-receipts skill instead. This skill is about invoice ↔ transaction matching, not document attachment.

Inputs

The user may provide:

• A workspace hint — an id, a workspace name, or the company behind it — if they manage more than one.
• 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:

• welllistworkspaces — how define-workspace resolves the workspace.
• wellqueryrecords — read invoices, transactions, invoicetransactions, exchangerates.
• wellgetschema — call this before querying any root for the first time in a session, especially invoices, transactions, and invoice_transactions — field names and relation paths (e.g. counterparty identity, the transaction-to-match join) vary by connector and workspace, never assume them.
• welllistconnectors — how connect-tools surfaces install links.
• Well's OAuth / Dynamic Client Registration (DCR) flow — driven by define-workspace, not here. Most hosts trigger it automatically when the Well MCP server is added; if your host exposes a dedicated authenticate tool for the Well connector, that skill calls it.

Workflow

1. Pin the workspace.

Call each list or read tool once per step, and render at most one card that AWAITS AN ANSWER per turn. The cards refresh themselves. A card whose click executes server-side and prefills a message in the user's composer is what ends the turn, and the sent message is how the routine resumes — so it is the WAITING that a turn may only do once, not the drawing. A read that renders a card and hands its result straight back in the same turn is not waiting on anything and does not consume that budget.

Confirm the Well MCP server is configured — if welllistworkspaces (or any well_* tool) is not available, tell the user a Well connection is mandatory at https://api.wellapp.ai/v1/mcp and stop until it's there.

Call welllistworkspaces().

• Auth error → no Well connection yet: start the Well connector's OAuth/DCR flow, then retry welllistworkspaces() yourself in the same turn and continue — do not ask the user to confirm they signed in.
• success: false with a non-auth error → retry once; on a second failure, do not invent a workspace — tell the user and give them <well-app-base-url> to open Well directly.
• Zero workspaces → the account has no workspace yet. Say so, point the user to Well to finish signing up, and return resolution: unresolved.
• session.pinnedworkspaceid set, and THIS conversation established it (its own picker click or typed choice earlier in the conversation), and the user is not asking to pick or switch → use it silently, map it to its row, resolution: userpicked, skip straight to the hand-off. A non-empty session.workspacequeue alongside it means a multi-pick is mid-walk — hand off multi_picked with the pin first and the queue behind it.
• session.pinnedworkspaceid set, but this conversation never rendered the picker nor took a typed choice → it's another conversation's leftover. Ignore it and resolve as if unset. Never mention it — "already pinned" is forbidden phrasing — and never skip the picker because of it.

Resolve without asking when you can:

• Exactly one workspace → use it, resolution: single. Say which one in one line; do not ask for confirmation and do not call wellswitchworkspace.
• Several workspaces and a hint (a workspaceid, name, or company behind it) → match it exactly on workspaceid; otherwise case-insensitively on workspacename, identity.registeredname, identity.tradename, or — for a country hint such as "my US entity" — on identity.country (ISO code). Exactly one match → use it, resolution: hintmatched, say which one you matched, and call wellswitchworkspace({ workspace_id }) so a later call can't fall back to a sibling entity. Zero or several matches → fall to the picker below; never pick the closest name.
• A hint naming several entities ("FR and US", "both my companies") is a sequence, not an ambiguity — split it into fragments, match each exactly as above, keep the user's order. Every fragment matching exactly one distinct workspace, and at least two distinct workspaces matched → call wellswitchworkspace({ workspaceids: [...] }) once, in that order — the first is pinned, the rest become the session's workspacequeue — resolution: multi_picked. Any fragment matching zero or several workspaces → fall to the picker; never resolve part of a compound hint and drop the rest silently.

With several workspaces and no usable hint, end the turn on the card: the welllistworkspaces result already rendered the picker (one tile per workspace, multi-select). Don't restate the workspaces under it. End with one short line naming the entities — "to match payments against invoices" — and stop. In a text-only host, list each workspace on one line (name, country, base currency, "(default)" on the primary) and ask the same one-line question. Never default to the primary workspace on the user's behalf.

Resolve the next message after the card, in this order, never by re-asking:

• The message is the card's prefill ("Continue in <name>", or the multi form "— then …") → the click already pinned it server-side. Acknowledge in half a sentence and continue — never re-verify with an extra call, never call wellswitchworkspace for it. A single name → resolution: userpicked; the multi form → resolution: multipicked.
• The message names one or more workspaces in its own words → map each to its workspaceid from the earlier result — never a guessed id — then call wellswitchworkspace yourself (workspaceid for one, workspace_ids for several, in the user's order). A name matching zero or several rows is asked about, never guessed.
• The message declines ("later", "not now") → resolution: unresolved. Say nothing was pinned and stop; do not call wellwaitfor_selection, do not run any workspace-scoped call.
• Any other message that needs the workspace → call wellwaitforselection({ kind: "workspace", timeouts: 10 }) once. selected → continue on selection.workspaceid (an empty selection.workspacequeue is userpicked, non-empty is multipicked). noselectionyet → one line asking to click the card, end the turn.

hasbanktransactions rides the hand-off because a later step needs it and only this one reads the workspace rows. It is true only when a connector the workspace BANKS with has already delivered a transaction — an accounting platform or a payment processor does not count, and neither does a transaction whose connector is unknown, disconnected or retired. false means no such transaction was found and null means the signal could not be read, so an absent value is never a zero, and no value here licenses skipping a bank-connection step.

Emit the hand-off:

workspace_id: <uuid>
workspace_name: <name or null>
is_primary: <true|false>
identity:
  registered_name: <value or null>
  trade_name: <value or null>
  country: <ISO code or null>
  base_currency: <ISO code or null>
  fiscal_year_start_month: <1-12 or null>
has_bank_transactions: <true|false|null>
resolution: single | hint_matched | user_picked | multi_picked | unresolved
workspaces: [{ workspace_id, workspace_name, identity, ... }, …]  # multi_picked only — pinned entry first, then the queue in order

On unresolved, every other key is null. Pass workspaceid explicitly on every well* call from here on, pinned or not — a pin changes what an omitted argument falls back to, it does not make the argument optional.

On multipicked: the caller runs its whole walk on the pinned workspace first, then calls wellswitchworkspace({ workspaceid: <next> }) on the next queue entry (read from welllistworkspaces' session.workspacequeue, never from chat) and repeats. Each pass carries its own workspaceid explicitly and gets its own recap — nothing is merged across two entities: no shared row, no combined total.

Verify before moving on: exactly one workspace is pinned, or resolution: unresolved — never two, never a merged view; session.pinnedworkspaceid was trusted only when this conversation established it; a hint resolved only on an exact id match or an unambiguous case-insensitive name match; wellswitchworkspace was called exactly once on a hint match or typed pick and not at all for a pick the card itself already made; on multi_picked, the loop rule (one entity at a time, own recap, no merging) was stated in the hand-off.

1. Confirm the connections this answer needs.

The workspace is already pinned — pass its workspace_id on the call below; do not re-resolve it here.

Read the current coverage in one call: welllistconnectors({ workspaceid, fromselection: true }) when this run follows a vendor pick; welllistconnectors({ workspaceid, kind }) when the job covers exactly one kind; welllistconnectors({ workspaceid }) otherwise (one unscoped call for two or three kinds — one call renders one card, and a turn draws at most one card that AWAITS AN ANSWER).

For each of the requested kinds —

• bank
• invoicing
• accounting

— keep only rows whose direction is input and whose datadomains contains that kind (never a display name or categoryid), and read each qualifying row's state in this order, first match wins:

1. to_configure or disabled → missing.
2. needreconnect, error, or suspended → error — offer installurl as a reconnect, not a first install.
3. enabled with lastsuccessfulsyncat set → connected (note "data may be partial" if syncin_progress: true).
4. Otherwise (enabled or processing, no successful sync yet) → connecting.

At least one connected row for a kind → connected, and name any error row for that same kind alongside it (a live connector does not cancel a dead one). Only connecting rows → connecting. Only error rows → error, name the connector, offer the reconnect link. No qualifying row → missing, including a to_configure row the user started but never finished.

This is a coverage read for a data skill, not a connect step: hand the per-kind states straight back in the same turn. No closing question, no wellwaitfor_selection, no card acknowledgment to wait for. When a required kind is missing, say so in the hand-off.

On a transient welllistconnectors failure, retry once; on a second failure, do not invent coverage — say it's unknown, give the user <well-app-base-url>/workspaces/<workspace_id>, and hand the failure back to the caller with no coverage claim.

Hand off, kept for the caller and never printed as a block: per requested kind, its state (connected/connecting/error/missing), the connector(s) behind it, and the installurl to act on; coverage — complete when every requested kind is connected or connecting, none when none is (an all-error workspace is none, not partial), partial otherwise; skippedby_user; required echoed back.

Verify before moving on: welllistconnectors was the only connector-listing tool called — no wellqueryrecords on workspaceconnectors, no provider-specific tool; each kind's state came from the four-line precedence above, not from a name or isconnected alone; coverage: none was used (not partial) when every requested kind was in error; a transient failure was retried once before the fallback link.

- coverage: none → stop; there is nothing to reconcile yet. - Any kind reported connecting, or a connected connector whose latest sync is still running → carry on, and carry "the data may still be partial" into the answer. - coverage: partial → carry on with what is connected, and keep the missing kinds for the coverage disclosure the Output requirements ask for. - A kind the user chose to skip comes back under skippedbyuser — respect that and don't re-ask for it in this run.

1. Verify the data itself has landed. Coverage reports connections, not rows — a connector can be connected and still have delivered nothing this skill can use. Spot-check what this skill actually reads: a 1-row wellqueryrecords read on invoices and on transactions. Zero rows on both means there is nothing to match yet — say so and stop. Reconciliation needs both sides: if only one root has rows, say which side is missing rather than reporting everything on the populated side as unmatched.

1. 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 wellgetschema({ root: "invoices" }) and wellgetschema({ root: "transactions" }) if not already called this session. - Search by whatever the user gave: an invoice number/reference (wellqueryrecords on invoices with ilike/eq on invoicenumber/referencenumber), a transaction date + amount (on transactions, using the nested instructedamount.amount/instructedamount.currency fields, not a plain scalar), or a counterparty name (via the debtorpaymentmeans/creditorpaymentmeans relation — 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 wellgetschema({ root: "invoicetransactions" }), then query invoicetransactions filtered by that invoice's or transaction's id. Report the matched counterpart (the other side of the join) along with matchmethod, confidence, edgestatus, allocationtype, and reasoning if present. - If no invoicetransactions row 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 invoicetransactions row — call wellgetschema 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 invoicetransactions 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.

1. Normalize currency.

The workspace is already pinned — pass its workspace_id on every call below.

Group the input amounts by currency for the rate lookup only — keep every tagged row, since the rate found for a currency gets applied back to each of its rows later, not just to a subtotal.

Settle the target currency: the caller's value if given, otherwise the workspace's identity.base_currency. If both are absent, ask rather than guessing, or fall back to reporting per currency and say why.

Take the single-currency shortcut (report the one total, resolution: singlecurrency, no rate lookup) only when that one currency already equals the target currency, or when the mode is percurrency. A lone foreign currency, with conversion asked for, is not a shortcut — convert it like any other.

Read each non-target currency's rate: wellgetschema({ root: "exchange_rates" }) once per session, then look up the pair as of the as-of date (default today). An exact-date rate → use it. No exact-date rate → use the most recent rate at or before the as-of date, and record that date — never a rate dated after it, and never an arbitrary nearby one. Check pair direction against the schema before dividing rather than multiplying.

A missing rate excludes that one currency — leave it out of the converted total, keep it in the per-currency breakdown, carry it in excluded with the reason, and mark the total partial. Never drop a currency silently.

Convert per row, then total: apply each currency's rate to every tagged row in that currency, not just to its subtotal, then sum the converted rows.

Emit the hand-off:

target_currency: <ISO code or null>
as_of: <YYYY-MM-DD>
converted_total: <number or null>
per_currency:
  - currency: <ISO code>
    native_amount: <number>
    converted_amount: <number or null>
    rate: <number or null>
    rate_date: <YYYY-MM-DD or null>
    rate_is_exact: <true|false>
converted:
  - tag: <caller's row id>
    currency: <ISO code>
    native_amount: <number>
    converted_amount: <number or null>
excluded: [{ currency: <ISO code>, reason: <text> }, …]
partial: <true|false>
resolution: converted | per_currency | single_currency | unresolved

Verify before moving on: the single-currency shortcut was taken only when that currency already equalled the target or the mode was per_currency; every converted figure carries the rate and rate date used, with the fallback date stated when an exact-date rate wasn't available; no rate dated after the as-of date was used; a currency with no available rate was excluded explicitly and the total marked partial; no total blends currencies anywhere in the output.

- partial: true means a currency had no rate in Well. Name it and say the total covers the rest, rather than letting a quietly smaller total read as complete.

1. 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 matchmethod, confidence, edgestatus, and allocation_type clearly labeled — and currency + date on every amount. Include reasoning when 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: provisional or low confidence labeled 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-receipts for 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.

How this reaches the user. A Well MCP tool that ships a widget attaches _meta.ui.resourceUri to its result, and the host decides whether to draw it. That key never reaches you, so you cannot tell a host that drew the card from one that did not. Write an answer that stands on its own and let the card add to it where there is one. State the lookup result in text regardless — you cannot know whether anything drew it. What you must not add is a second rendering of what a card already shows.

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.
• The workspace came from the pinned hand-off, and its workspaceid rode every well* call.
• Connection state came from the coverage hand-off, and row presence was spot-checked separately in step 3; a connected connector was never assumed to mean usable data had landed.
• 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.
• wellgetschema was called before the first query against each root, especially before assuming any transaction ↔ counterparty or transaction ↔ invoice_transactions field path.
• A missing invoice_transactions row 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 provisional matches 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 from the coverage hand-off — 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

Pin the workspace, confirm connections, and spot-check that rows have landed; look up invoices by invoicenumber, then query invoicetransactions filtered by that invoice's id. Report the matched transaction with its date and amount, plus matchmethod, confidence, edgestatus, and allocationtype (e.g. "matched via llmmatched, 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

Pin the workspace, confirm connections, and spot-check that rows have landed; resolve the trailing-quarter window, call wellgetschema 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 instructedamount 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 invoicetransactions 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.

Voice

<!-- voice:begin --> Write like a brilliant, understated operations colleague. Hold the tone professional and casual at the same time, confident but never arrogant, credible but easy to follow, warm but never cute. This governs every message of the run, whichever step produced it. Precedence is fixed: when a step hands you an exact string to write, write it exactly as given, dashes and capitals included; these rules govern the prose you compose yourself.

Lead with the outcome, then the detail behind it. Write short active sentences a non-technical reader understands. Use sentence case for the headings and labels you write yourself. Name a real button or card label exactly as the app renders it, such as Use, Validate, Continue, or Deploy, so the user reads the same word on screen. Prefer a concrete number or a real example over an abstract claim.

Never write an em dash or an en dash. Use a period, a comma, or a colon instead. Never write an exclamation mark or an emoji. Keep an acknowledgement brief and specific, such as "Got it, pulling those invoices now." Skip preamble, superlatives, and self-praise.

Drop the habits that make an answer sound generic:

• Hedging transitions, such as "Furthermore", "Moreover", "Additionally", or "In today's fast-paced landscape".
• Buzzwords, such as leverage, delve, harness, foster, revolutionize, revolutionise, streamline, optimize, optimise, seamless, game-changer, cutting-edge, best-in-class, world-class, unparalleled, disruptive, synergy, blockchain, and crypto.
• Hollow contrast, such as "not just X, but Y".
• Vague praise, such as powerful, robust, intelligent, frictionless, elegant, or advanced.

Reach for these verbs first: ask, drop, connect, get, surface, compose, share, route, enrich, learn, reconcile, match, flag.

Keep to the house words in what you write to the user. Write "connect", never "integrate". Write "sessions", never "chat". Write "business data", never "financial data". Write "tokens", never "credits". Name every object by its own name, the workspace, the connector, the company, or the invoice, and never show the user a raw id on its own. A Well app address is a link, not an id, so keep it whole even when it carries a workspace id. <!-- voice:end -->