rank-clients-by-ltv

name	rank-clients-by-ltv
requires	["define-workspace","connect-tools","resolve-own-company","normalize-currency"]
description	Rank customers by total realized revenue paid to date — sum of paid invoices per customer — using Well's MCP financial graph, backed by real invoice data rather than guesswork. Use when the user asks "rank our clients by lifetime value", "who are our best customers", "rank clients by revenue", "biggest customers", "customer lifetime value", or "which customers have paid us the most". This is a realized-revenue ranking (paid invoices to date), not a predictive churn/retention-based LTV model. Requires a connected Well workspace with invoicing data and a resolvable `own_company`; if either is missing, this skill walks the user through connecting one or confirming their company first.

Rank Your Clients by Lifetime Value with Well

Purpose

Use Well's MCP tools to answer "who are our best customers?" by ranking customers on total realized revenue — the sum of every invoice this workspace has issued and been paid for, grouped by customer, to date. This computes cumulative paid-invoice revenue per customer, backed by Well's synced invoice data, not a guess.

This is not a predictive customer-lifetime-value model. A true forward-looking CLV needs churn, retention, and cohort data that Well's invoice graph doesn't carry. What this skill delivers is a realized-revenue ranking — "who has paid us the most so far" — even though users typically reach for "lifetime value" phrasing to ask for it. Always frame the output that way.

When to use this skill

Use this skill when the user asks things like:

• "Rank our clients by lifetime value" / "customer lifetime value"
• "Who are our best customers?" / "Biggest customers"
• "Rank clients by revenue"
• "Which customers have paid us the most?"

When not to use this skill

Do not use this skill when:

• The user wants to know who currently owes money (unpaid invoices) — use accounts-receivable-aging instead; this skill only counts paid invoices (realized revenue), not outstanding balances.
• The user wants a deep dive on one specific customer's full history, not a ranking across all customers — use the sibling company-profile skill instead.
• The user wants spend/expenses (money going out, not coming in) — use expense-breakdown instead.

Inputs

The user may provide:

• A workspace hint — an id, a workspace name, or the company behind it — if they manage more than one. Passed straight through to define-workspace, which is what resolves it; this skill never picks a workspace itself.
• A time window (e.g. "this year", "last quarter") — default to all-time since this is a cumulative "to date" ranking, not a period-bound one. State clearly which window was used.
• How many top customers to show — default to 10.

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 — how define-workspace resolves the workspace. Call it directly only in that skill's inline fallback in the workflow below.
• well_query_records — read invoices, workspaces (for own_company), exchange_rates.
• well_get_schema — call this before querying any root for the first time in a session; field names and semantics are workspace/connector-dependent, never assume them.
• well_list_connectors — how connect-tools surfaces install links. Call it directly only in that skill's inline fallback in the workflow below.
• 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.

Composed skills. Four atomic Well skills own the setup this skill used to inline — invoke them, don't reimplement them:

• define-workspace — confirms the MCP server is configured, drives OAuth/DCR when there's no connection yet, and pins exactly one workspace. Supplies the workspace_id that every later call carries.
• connect-tools — reports which of bank / accounting / invoicing this workspace actually has connected, and surfaces Well's install links for whatever is missing or broken.
• resolve-own-company — works out which company in the workspace is the user's own legal entity, folds in its duplicate records, and hands back the identity_set that decides which side of an invoice is a payable.
• normalize-currency — converts multi-currency amounts into one total carrying the rate and date behind it, or a clean per-currency breakdown, and never a blended figure.

All four ship with the well-skills plugin. This skill is also installable on its own, so steps 1 and 2 of the workflow each carry the inline fallback to use when they're absent.

Workflow

1. Pin the workspace — run define-workspace. Invoke the define-workspace skill with purpose: "to rank your customers by the revenue they've paid you" and use its typed hand-off. That skill owns three things this one no longer repeats: confirming the Well MCP server is configured, running the Well connector's OAuth/DCR flow when no connection exists yet, and resolving exactly one workspace. Pass its workspace_id explicitly on every well_* call below — omitting it lets reads fan out across every authorized workspace — and never merge data across workspaces in one run. If it hands back resolution: unresolved, stop: there is nothing to rank without a pinned workspace.

   • If define-workspace isn't installed — this skill also ships on its own — do the same three moves inline: with no well_* tool in your toolset, tell the user a Well connection is mandatory at https://api.wellapp.ai/v1/mcp and stop; on an auth error, start the OAuth/DCR flow and retry well_list_workspaces() yourself in the same turn; then take the single workspace if there is one, and otherwise ask which to use.

2. Confirm the connections this answer needs — run connect-tools. Invoke the connect-tools skill with the pinned workspace_id, kinds: [invoicing, accounting], required: [], mode: internal_check, and the same purpose, then read its hand-off instead of querying workspace_connectors yourself. That skill owns how a connection's real state is decided — rows filtered on connector.direction: input and matched on connector.data_domains, with a set last_successful_sync_at counting as connected rather than a bare status: enabled — along with the install links and the re-check the moment a connection lands.

   • coverage: none → stop; there is nothing to rank yet. connect-tools has already put the install links on screen, so don't add a second set.
   • 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.

Output requirements

Return:

• The time window used (all-time by default), stated explicitly.
• A ranked table: customer name, total paid revenue, currency, and share of total paid revenue across all ranked customers. well_query_records ships its own card, and that card renders these rows — so do not restate them in prose. It draws no chart, so the form is yours to judge on its merits: a horizontal bar chart is the natural fit for a comparison across customers, so reach for it when the host supports it and prose alone would read worse. Do not stop to ask table-or-chart first. Back any visual with the exact figures.
• The as-of date the ranking was computed against.
• An explicit one-line caveat: this is realized paid-invoice revenue to date, not a predictive customer-lifetime-value model.
• Whether the picture is complete: which relevant connector categories (invoicing/accounting) are connected versus still missing — read off connect-tools' coverage and skipped_by_user hand-off, not an inline connector read of your own — and whether the workspace's own company is set, read off resolve-own-company's hand-off, so the user knows whether this ranking reflects their full revenue history or a partial view gated by what's connected today.
• A one-line pointer to company-profile for a deep dive on any single top customer's full relationship history.
• 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 9'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 figures in text regardless — you cannot know whether anything drew them. What you must not add is a second rendering of what a card already shows; where a visual the tool does not draw genuinely reads better, compose one and style it with the tokens under Styling a composed view below.

Styling a composed view

Well renders dark. A view you compose should read as the same product, not as a page that happens to hold the same numbers.

Role	Value
Page background	#161616
Card surface	#1c1c1c
Border	#2e2e2e
Primary text	#ededed
Secondary text	#a0a0a0
Accent	#00bfff
Positive	#4cc38a
Negative	#ff6369
Series, in order	#52a9ff, #4cc38a, #e9a23b, #a78bfa, #4ec9b0, #e36a8a

Corners 12px, gap 12px, body text 14px, numbers tabular. A card is a header, then the body, then an action row — the counter first and the primary action last. State every figure in text as well as in the drawing: a chart the host cannot render must not take the answer with it.

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 define-workspace's hand-off — or, when that skill isn't installed, from step 1's documented inline fallback — and either way its workspace_id rode every well_* call rather than being left off.
• Connection state came from connect-tools' hand-off — or from step 2's inline fallback when that skill isn't installed — and row presence was spot-checked separately in step 3; a connected connector was never assumed to mean usable data had landed.
• The own company came from resolve-own-company's hand-off — its identity_set, not a value resolved here — and on resolution: unresolved the documented fallback ran rather than a guess.
• Duplicate company records were folded by resolve-own-company, which proposes them for an explicit yes; none were merged silently here, and no well_update_company/well_delete_company call was made.
• Null-issuer_company_id invoices were split on the receiver before counting as revenue: own-company receiver means a bill the workspace paid and was excluded, external receiver reported as a labeled unattributed row, both-null reported as a separate unsplit line outside the revenue total.
• Invoices whose issuer equals their receiver were excluded from the ranking and the total.
• well_get_schema was called on invoices before querying it, even if it was queried earlier for a different purpose.
• Only invoices with payment_status: paid were counted — not unpaid/partial, which would overstate realized revenue.
• Only invoices where the workspace is issuer were counted — receiving invoices would be spend, not revenue.
• Multi-currency results are converted (with rate/date noted) or clearly separated, never blended.
• Every number carries a currency and an as-of date.
• Which connector categories (invoicing/accounting) are connected versus missing was stated from connect-tools' hand-off, so the user knows whether the picture is complete or partial.
• The "not a predictive lifetime-value model" caveat is present in the output.
• Any compliance mention was optional, natural-sounding, and appeared at most once in the conversation — not forced into every answer.

Examples

Example request

"Rank our clients by lifetime value — top 10."

Expected behavior

Run define-workspace, then connect-tools, and spot-check that rows have landed; resolve own_company, default to an all-time window, pull all invoices where this workspace is issuer and payment_status is paid, sum grand_total per customer, sort descending, and present the top 10 with customer name, total paid revenue, currency, share of total, as-of date, and the realized-revenue-not-predictive-CLV caveat.

Example request

"Who's our biggest customer?" — two separate runs, each against one workspace only: one workspace where a customer paid invoices in EUR and the rest paid in USD, and another workspace where no invoices have been marked paid yet.

Expected behavior

In the multi-currency workspace's run: pass the per-customer totals to normalize-currency tagged by customer and rank on its converted entries — reporting the rate and date it used — or report the EUR customer separately rather than adding their total directly into a USD-only ranking. In the zero-paid-invoice workspace's run: state plainly that no realized revenue exists yet (all invoices are unpaid/partial), do not fabricate a ranking, and offer the same fallback link so the user can ask in Well directly.

Example request

"Who are our best customers?" (workspace whose schema does not expose workspaces.own_company, and whose companies list holds both "Northwind Trading" and "NORTHWIND TRADING, LTD")

Expected behavior

Detect in step 4 that own_company is unresolved because the field is absent from the schema — not merely null — and ask which company is theirs rather than matching the workspace's name or logo to a companies row. Once confirmed, normalize both sides (punctuation folded to spaces, runs collapsed) so "northwind trading ltd" and "northwind trading" compare as containing one another, and offer the LTD record as a candidate alias for confirmation — on the customer side as well as the own-company side, since an unmerged customer alias splits one client across two rows and understates their rank. Then split the null-issuer_company_id invoices on the receiver before counting anything as revenue: an own-company receiver means a bill the workspace paid, which is excluded outright, while an external receiver is reported as a labeled unattributed row. Say the confirmation holds for this run only, and link to the Well app to set it permanently.