List missing invoices
well_list_missing_invoicesList the supplier invoices a past period is still missing — the settled spend whose invoice has not been collected, one row per counterparty, exactly as the Well app's expense-invoices card shows them. Use it for "which invoices am I missing for ?" and as the input to fetching them. It does NOT list the connection routes a provider offers; for "which connectors, extension, mailbox or drive can bring in this provider's invoices" call well_list_connectors with counterparty_ids copied from these rows.
Name the period ONE way: { calendar_year, calendar_month } (the calendar month, e.g. June 2026 → 2026, 6), { fiscal_year, fiscal_period }, or periods: [{ calendar_year, calendar_month }, …] for SEVERAL months in one call (1-12), or name NO period at all to use the months the user selected on the period card in this conversation (well_list_periods → the user clicks → well_switch_workspace records them). With no period named and no months selected, the call refuses and tells you to run the period step first. Every month must have ended: a current or future month is refused, and so is the adjustment period (13). Duplicate months are refused.
COST: there is no batch endpoint, so each named month is a separate read of that month's spend. Ask for the months the user actually named, not a whole year "to be safe".
Returns rows, ONE per counterparty for the whole call, never one per month. Each row carries name, tx_count and base_total_amount in base_currency SUMMED over the months it covers, its own months array naming those months (each with that month's tx_count, base_total_amount, proof_task_id, acquisition_status and refusal_reason), and the route fields mode, available_modes, suggested_action, matched_provider_name and matched_connector_service_id, which the provider match resolves once per counterparty. NEVER list a counterparty once per month and never present its months as separate gaps: it is one supplier to chase, and one collection covers every month behind it. Name the months a row spans from its months array. The envelope's own months carries each month's totals (rows are NOT repeated there), periods_covered names the months read, and transaction_count, group_count and dropped_groups are totals across every month read. row_count counts the DISTINCT counterparties, so it is never the sum of the months' own row_count. dropped_groups counts the GROUPS that produced no row — party-less bank operations, unresolved counterparties, unnamed companies — never transactions, and bank_internal and unknown hold one group per month whatever they contain, so quote neither as a quantity of operations. unknown and unnamed_company ARE categorized expense spend still missing a supplier invoice, so an empty rows over a non-zero count is not a complete period; bank_internal alone is, since no supplier can invoice a party-less operation. The single-month fields calendar_year, calendar_month, fiscal_year, fiscal_period and period_label appear ONLY when the call named exactly one month.
totals_by_currency is the money still missing an invoice, ONE set per currency in the lines' own currency: gross, the copies and own_company movements it holds, and net. The rows never hold a copy or a movement between the user's own accounts, and party-less bank operations sit in no figure, so net is the money of the lines behind rows plus the unknown and unnamed_company groups, which produce no row. possible_duplicates holds the money of the bank lines that are half of a pair Well cannot tell apart (two lines of the same amount to the same supplier on the same day): the second line of such a pair is left out of net until the person says both are real payments, so net counts that money once. The figures are read apart from the rows, so a cut list (candidates_truncated) still carries the full figures. Quote net as the gap, in the currency it carries, and quote gross, copies and own_company only as they come. Every amount here and in rows is in major units of its currency, as a person writes it: a net of 52300 in USD is 52 300 $, never 523,00 $. Never divide, multiply or otherwise scale one. NEVER add, subtract, round, halve or convert a figure, and never merge two currencies into one number. own_company is money that moved between the user's own accounts: name its amount in one line as left out of the gap. copies is bookkeeping: never name it to the person. totals_by_currency: null means the figures could not be read: quote no amount, and never present it as zero.
possible_duplicate_pairs lists the pairs of bank lines Well cannot tell apart: two lines of the same amount to the same supplier on the same day, with no invoice behind either. The SECOND line of each pair is held out of net (it sits in possible_duplicates), so the total counts that money once, and the row that holds it carries possible_duplicate: true. Show one line per pair and ask the person once: are both lines real payments (keep) or does the second one repeat the first (drop)? Record each answer on its own with well_upsert_preference: key missing_invoice_duplicate_verdicts, scope workspace, the pair's namespace as namespace, value { "decision": "keep" | "drop" }. A keep puts the second line back in the total, a drop keeps it out, and either way the pair is never asked again. Never decide the answer yourself, never leave a pair out of the total in silence, and never add the held amount back to net by hand: quote the figures as they come.
CURRENCY: base_amount and base_total_amount are in base_currency, the workspace base currency, which each row, month and transaction carries beside them. It can differ from the currency the transactions were paid in and from the currency of the person's language. Write every base figure with the symbol or code of its base_currency (USD → $, EUR → €, GBP → £; another code as the code), and write a transaction's amount and a totals_by_currency figure with their own currency. A reply in French for a USD workspace still writes a base_total_amount of 120.4 as 120,40 $, never 120,40 €. Never relabel or convert a base figure into another currency: to state a figure in the currency the money was paid in, quote the transactions' own amount and currency.
Pass the limits of the ask as arguments and render nothing beyond them. row_limit is the count the person named (0 for "just the total": no row comes back and one line answers), order: "amount" puts the biggest gap first for "the biggest", and no_action: true says the person wants nothing fetched or started, so offer no fetch. listed_in_reply: true says that your own reply lists the rows and says what starts, so the phone draws no list and no fetch offer under it. The result echoes the four values, and row_count still counts every counterparty found while rows_omitted counts the rows the limit left out. rows_omitted_total is the money of those left-out rows in base_currency, summed by Well: quote it as it comes on the line that counts the other suppliers, and give the count alone when it is null. unattributed_total is the money of the spend with no named supplier (the unknown and unnamed_company groups), summed by Well: quote it as it comes on its own line after that one, so the parts add up to the net when totals_by_currency holds one set in base_currency, and give no amount for those groups when it is null.
Every row also carries transactions — the counterparty's own lines behind the row, each with date, description (the bank's remittance text), category, amount, currency and base_amount. amount is signed and stays in the transaction's own currency, so never add those together across a row; base_amount is the same line in base_currency, and the magnitudes of those DO add up to base_total_amount, unless the row carries possible_duplicate: true: a held line stays in transactions while the row's figure leaves it out. The list is capped at 25 per row and transactions_omitted says how many the cap left out — quote that number instead of implying the list is complete.
mode is the ONE route the card suggests for that row: agent (a browser agent can collect it from the supplier portal), connect (connect the named service and Well fetches it), upload (the user supplies the file). available_modes lists every route the row offers instead of only the suggested one — agent and upload on every row, plus connect when the catalog holds a connector for the matched provider, so 2 or 3 entries. Present mode as the suggestion and available_modes as the choice. available_routes is the order to look for the invoice in, mail_search first when the caller's own Gmail is connected: try the routes in that order and stop at the first find, so one invoice is found once.
Only CATEGORIZED expense transactions are considered — uncategorized spend is not listed, so poor categorization coverage under-reports the gaps; disclose the hints.
This tool reads the user's data and changes none of it. It does not mint tasks, start a close, connect anything, or fetch any invoice.
Call this directly — no workspace call is needed first (workspace is resolved from the caller's authorized token, same as every other well_* tool).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| order | No | `amount` puts the biggest gap first (by `base_total_amount`, rows without a figure last). Pass it for "the biggest", "the largest", "the most expensive". Omit it for the default order. | |
| periods | No | Several calendar months in one call, 1-12. Each month costs one separate read, so name only the months you need. Duplicates are refused. | |
| no_action | No | true when the person asked for nothing to be fetched or started ("ne récupère rien", "just tell me", "don't fetch anything"). The reply then offers no fetch and shows no action link. Omit it otherwise. | |
| row_limit | No | How many rows the person asked for, 1-15. Pass it when the ask names a count ("the 3 biggest", "the top 5"). Pass 0 when the ask is for the total alone ("just the total", "juste le cumul"): the result then carries no row and one line is enough. Omit it when the ask names no count. | |
| fiscal_year | No | Fiscal year (the calendar year the workspace's fiscal year STARTED in). | |
| workspace_id | No | Target workspace. This read reports one workspace's own data. Omit it and the token's primary workspace answers, which may not be the one you mean; the result names the workspace that did. | |
| calendar_year | No | Calendar year, e.g. 2026. | |
| fiscal_period | No | Fiscal period, 1-12. The adjustment period (13) is refused: it has no calendar month. | |
| calendar_month | No | Calendar month, 1 = January … 12 = December. | |
| conversation_id | No | The conversation id returned by the previous Well result, in its meta under well/conversation_id, in its structuredContent, or in its JSON text block. Pass it back on every call in the same conversation, including a call a card makes, so the chosen workspace and the earlier answers still apply. It decides the conversation on its own: nothing the host states about the session replaces it. Omit it only on the first call of a conversation. | |
| listed_in_reply | No | true when your own reply lists these rows and says what starts and what waits, as the WhatsApp gap recap of a skill does. The phone then draws no list and no fetch offer under your reply. It says nothing about what the person asked: pass `no_action` for that. Omit it otherwise. | |
| workspace_scope | No | Restrict this call to the family: the token's primary workspace plus the company workspaces under it that you are a member of. Unrelated authorized workspaces drop out of the read; row reads merge across the family, while a per-workspace figure still reports exactly one workspace. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| rows | Yes | The card's rows, ONE per counterparty for the whole call, in the order the oldest month listed them, each naming the months it covers in `months`. A counterparty owing an invoice in several of the months read is one row, never one per month. | |
| error | No | ||
| hints | No | ||
| order | No | The `order` the rows are in, echoed. | |
| months | No | Per-month totals, oldest first. | |
| success | Yes | ||
| next_step | No | What to do with the card this result renders. Added by the dispatcher when the card asks for a click. | |
| no_action | No | The `no_action` the call was made with, echoed. | |
| row_count | No | The DISTINCT counterparties the call found, before any `row_limit` cut `rows`. Never the sum of the months' own `row_count`. | |
| row_limit | No | The `row_limit` the call was made with, echoed; null when the ask named none. | |
| fiscal_year | No | Present only when the call named exactly one month. | |
| group_count | No | Groups the reads returned before the card's projection. | |
| period_label | No | Human-readable label of the period, e.g. "June 2026". Present only when the call named one month. | |
| rows_omitted | No | Rows the `row_limit` left out of `rows`. Zero when no limit cut the list. | |
| workspace_id | No | ||
| base_currency | No | The workspace base currency (ISO 4217) of every `base_amount` and `base_total_amount` in the result. Each row, month and transaction repeats it beside its own base figures. | |
| calendar_year | No | Present only when the call named exactly one month. | |
| fiscal_period | No | Present only when the call named exactly one month. | |
| calendar_month | No | Present only when the call named exactly one month. | |
| dropped_groups | No | ||
| conversation_id | No | The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation. | |
| listed_in_reply | No | The `listed_in_reply` the call was made with, echoed. | |
| newly_connected | No | Tools that connected to this workspace since the last result and that no session was told about yet, oldest first. Present only when at least one tool is new. The connected-line rule says when to tell an entry; when it does, one line per entry, in the person's language: "<name> is connected.". Never fold several entries into one sentence. Each entry comes back once, on one result only: never repeat its line later. | |
| periods_covered | No | The months the result covers, oldest first. | |
| periods_requested | No | How many calendar months the call named. | |
| transaction_count | No | Every transaction missing its invoice, across all groups and all months. | |
| resolved_workspace | No | The workspace that answered, when the caller named none and the token authorizes several. | |
| rows_omitted_total | No | The money of the rows the `row_limit` left out, summed by Well over those rows' `base_total_amount`: the amount of the line that counts the other suppliers. It covers the same suppliers `rows_omitted` counts, never the `unknown` or `unnamed_company` groups. Null when no row was left out, when a left-out row has no figure, or when `candidates_truncated` is true: then give the count of the other suppliers alone, with no amount. | |
| totals_by_currency | No | The money still missing an invoice, ONE set per currency in the lines' own currency, in major units (not cents). Quote `net` for the gap and never add, round, halve or convert any figure yourself. `copies` and `own_company` are what `gross` holds that is not a gap: name the `own_company` amount in one line as left out, and never name `copies` to the person. Two currencies are two figures: never merge them. Null when the figures could not be read: then quote no amount at all, and never read null as zero. | |
| unattributed_total | No | The money of the `unknown` and `unnamed_company` groups, summed by Well over their `base_total_amount`, in `base_currency`: the amount of the line for spend with no named supplier. A held possible duplicate line that no row holds leaves this sum, as it leaves the `net`. These are the groups the card cannot key or name: a group with no counterparty, a company group with no name, and a named company group with neither a proof task nor a company id. The `net` of `totals_by_currency` holds it, and no row and no `rows_omitted_total` does, so the rows, `rows_omitted_total` and this amount add up to the `net` when `totals_by_currency` holds one set and its currency is `base_currency`. Null when no such group, when one has no figure, when a held possible duplicate line falls outside the read's sample, or when `candidates_truncated` is true: then give no amount for those groups. | |
| candidates_truncated | No | True when a month's read hit its line cap, so `rows`, `row_count` and `transaction_count` miss lines. `totals_by_currency` is read apart and still covers every line. Say the list is cut when this is true. With `order` set to `amount`, the rank then covers only the lines read: call the rows the biggest of those lines, never the biggest of the period. | |
| conversation_id_note | No | Present only when the server opened a fresh lane, stating that no choice recorded earlier was read. | |
| conversation_id_source | No | Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened. | |
| totals_unreadable_count | No | Lines with no readable amount. They sit in no figure of `totals_by_currency`. Null with it. | |
| possible_duplicate_pairs | No | The pairs of bank lines Well cannot tell apart: two lines of the same amount to the same supplier on the same day, with no invoice behind either. The SECOND line of each pair is held out of `net` and sits in `possible_duplicates`, so the total counts the money once. Ask the person for each pair whether both lines are real payments (`keep`) or the second one repeats the first (`drop`), and record each answer with `well_upsert_preference` under the key `missing_invoice_duplicate_verdicts`, `scope: "workspace"` and the `namespace` of the pair, value `{ "decision": "keep" | "drop" }`: a `keep` puts the line back in the total, a `drop` keeps it out, and either way the pair is never asked again. Empty when the read found no such pair. | |
| possible_duplicates_unavailable | No | True when the possible-duplicate check could not run, or its pair list was cut at its cap: some pairs may be missing from `totals_by_currency` and `possible_duplicate_pairs`. Say in one plain line that possible duplicates could not be checked, then quote the figures as they come. |