Preview invoice fetch
well_preview_invoice_fetchPreview which vendors a past period is still missing supplier invoices from, where each one's invoices are, and which route would obtain them. Use it for "what would happen if I fetched 's missing invoices?" before anything runs.
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 vendors — EVERY vendor of the rows THIS CALL covers, one entry per supplier portal ACROSS the whole window (one portal is one place to go, however many months it spans), or one per counterparty where no portal matched: name, provider_id, domain, url and url_source, the counterparties it covers (each tagged with calendar_year, calendar_month, period_label and suggested_route), tx_count, base_total_amount in base_currency. THE ROUTE NEVER FILTERS vendors: a vendor Well has no published flow and no connector for is listed exactly like the rest, with its route on its counterparties. WHAT the call covers is a separate question, and two fields answer it: a counterparty pick narrows the rows to the picked companies (see scoped_to_selected_counterparties below), and a hints line names any group the projection could produce no vendor for. So vendors is every vendor of the rows THIS CALL covers, which is the whole period only when neither of those is present. upload_rows (the user must supply the file) and connect_rows (connecting the named service fetches it) carry the same counterparties again, split by route, with the same month tags.
WHERE A VENDOR'S INVOICES ARE: url_source says how much url knows. "blueprint" is the page Well's own published flow opens, so it IS the billing page. "enrichment" is the vendor's front door — the catalog entry address or the company's domain — so the user still has to find the invoices on it. "none" means no address at all and url is null. Never present an "enrichment" address as the invoice page. url_source informs and gates nothing: an "enrichment" vendor is offered for the pick, and carried on the link, exactly like a "blueprint" one.
ROUTES DESCRIBE HOW, NOT WHETHER: a counterparty Well holds a connector for is in connect_rows AND under its vendor, where its entry reads suggested_route: "connect" and connect_routed_counterparties counts it. Connecting is the route to suggest; the agent run stays available so the user has a way through when the connector does not work for them. A counterparty on suggested_route: "upload" is in upload_rows too. Never present the same counterparty as two separate gaps — it is one gap seen twice, so count it once.
counts covers the rows this call actually read, and every field states its own unit: vendors and agents count PORTALS, agent_tx counts TRANSACTIONS, upload and connect count COUNTERPARTY ROWS — one counterparty per month. They are not summable with each other: never add them into one total, and vendors is never the sum of the other four, because every counterparty reaches the vendor list whichever route it takes. A total over the whole window counts the DISTINCT counterparties named in vendors, and a counterparty appearing again in upload_rows or connect_rows is the same gap seen by its route. Across several months a counterparty counts once per month in upload and connect, while vendors and agents count each portal once for the window, so neither is the sum of the months' own. WHEN scoped_to_selected_counterparties IS PRESENT, vendors, upload_rows, connect_rows, counts AND months COVER ONLY THE PICKED COUNTERPARTIES, NOT THE WHOLE WINDOW: for the months the pick bounded, every row and every figure here is built from the picked rows alone, and selection_scope says how many counterparty rows it left out. Never report those rows as every vendor the period is missing an invoice from, and never report those counts as the period's own — state the truncation and its size, and point at well_list_missing_invoices for a fresh card that drops the pick. Without that field the counts cover the whole window. months gives each month's own counts; periods_covered names the months. A sum is null when any member of it had no FX rate, never a partial figure. The single-month fields calendar_year, calendar_month, fiscal_year, fiscal_period and period_label appear ONLY when the call named exactly one month.
THIS TOOL LAUNCHES NOTHING. It creates no task, starts no run, and fetches no invoice — mode is always "preview" and nothing_launched is always true. Launching the agents is NOT available on this surface, so present the preview as information and do not promise to run it.
collect_url is the ONE link to hand the user: the /collect page, which asks the Well browser extension to run these portals. It names each portal by its provider_id, and that id is the only field that decides which portal runs — a name or an address in the link labels a row and nothing more. Give the link as returned and never build one or edit its parameters. The page starts nothing until the user acts on it, it reports which portals the extension accepted, and it never reports that an invoice arrived. The link also names this workspace, and that name gates WHO may act on the link: the page starts nothing until the reader is signed in to Well as a member of it. It does NOT choose where the invoices land — the extension files into whichever workspace it is signed in to — so never tell the user the link picks the destination. THE LINK CARRIES EVERY VENDOR THAT HAS AN ADDRESS, whatever its url_source and whether or not Well holds a published flow for it. Deciding what a vendor's invoices need once the page opens belongs to the app and the extension, not to this read, so url_source labels a vendor and never withholds it. Two things still keep a vendor off the link: no address at all, and no provider_id the link can address. collect_url is null when the window holds no addressed vendor at all; collect_url_omits names the vendors a full window pushed past the 25-portal ceiling, and collect_url_unaddressable names the ones the link cannot name. A vendor on either list is still missing its invoice, so say the link cannot carry it, and offer the upload or the connect route from upload_rows and connect_rows instead. Never say it has nothing outstanding.
Only CATEGORIZED expense transactions are considered — uncategorized spend is not counted, so poor categorization coverage under-reports what an agent run would cover; disclose the hints.
Call this directly — no other tool 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 |
|---|---|---|---|
| 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. | |
| 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. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | ||
| error | No | ||
| hints | No | ||
| counts | No | The whole window's counts. `vendors` and `agents` count the distinct portals across it, so neither is the sum of the months' own. `upload` and `connect` add each month's counterparty rows, so a counterparty missing an invoice in two of the months read counts once per month. | |
| months | No | Per-month route counts, oldest first. | |
| success | Yes | ||
| vendors | Yes | EVERY vendor of the rows THIS CALL covers, whatever route its invoice would arrive by — one entry per supplier portal across the whole window, or per counterparty where no portal matched. The ROUTE never filters this list: a vendor Well has no published flow and no connector for is listed exactly like the rest. What the call covers can still be narrower than the period, and the envelope says so: when `scoped_to_selected_counterparties` is present these are the picked counterparties alone and `selection_scope` sizes the remainder, and a `hints` line names any group the projection could produce no vendor for. | |
| next_step | No | What to do with the card this result renders. Added by the dispatcher when the card asks for a click. | |
| collect_url | No | The `/collect` entry that hands these vendors to the Well browser extension, naming each one by its `provider_id` and naming this workspace as the link's authorization scope. The page starts nothing until the reader is signed in to Well as a member of it. It carries every vendor that has an address, whatever that address's `url_source`, because what a vendor's invoices need once the page opens is the app's and the extension's decision rather than this read's. Null in three unrelated cases: no vendor of the window carries an address, none of the addressed vendors carries an id the link can address, or this read could not name the workspace the link authorizes. The hints name which one, and only the first is a verdict on the vendors. Opening it starts nothing on its own: the user acts on the page. | |
| fiscal_year | No | Present only when the call named exactly one month. | |
| upload_rows | Yes | Counterparties whose invoice only a manual upload can obtain. | |
| connect_rows | Yes | Counterparties whose invoice arrives by connecting a service. | |
| period_label | No | Human-readable label of the period, e.g. "June 2026". Present only when the call named one month. | |
| workspace_id | No | ||
| base_currency | No | ||
| 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. | |
| 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. | |
| periods_covered | No | The months the result covers, oldest first. | |
| selection_scope | No | What the pick removed. Present with `scoped_to_selected_counterparties`, so the size of the truncation is readable beside the result. | |
| nothing_launched | No | Always true — this tool never starts anything. | |
| collect_url_omits | No | The portals `collect_url` does NOT name, because one link carries at most 25. Present only when the ceiling left some out. Report those vendors as outside the link — it starts nothing for them. | |
| periods_requested | No | How many calendar months the call named. | |
| resolved_workspace | No | The workspace that answered, when the caller named none and the token authorizes several. | |
| 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. | |
| collect_url_unaddressable | No | The vendors `collect_url` does not name: the vendor carries no address at all, or it carries one but no catalog id the link can address. A missing published flow is NOT among the reasons, because the link takes an enrichment address exactly like a blueprint one. Present only when the window holds some. They are real gaps and they are listed in `vendors`; report them as vendors the link cannot carry, never as absent. | |
| rows_dropped_by_ownership | No | Counterparty rows this preview dropped because the current user owns none of their gaps — a fetch runs as the current user and can only collect the invoices of counterparties they own. Counted apart from `selection_scope.rows_dropped_by_filter` (the pick's own shortfall), and present only when it dropped at least one. The matching `hints` line names it. | |
| scoped_to_selected_counterparties | No | Present when a counterparty pick narrowed this preview: for the months the pick was made against, every route below covers only those companies. A month outside the pick is covered in full. |