well_preview_invoice_fetch

io.github.WellApp-ai/well-mcp · Verify this server

Preview which invoice agents a past period WOULD launch to collect its missing supplier invoices, and what the rest of the gaps would need instead. Use it for "what would happen if I fetched <month>'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 this session (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 `agents` — one entry per supplier portal an agent would run ACROSS the whole window, because one agent run covers one portal however many months it spans: `provider_name`, `provider_id`, the `counterparties` it covers (each tagged with `calendar_year`, `calendar_month` and `period_label`), `tx_count`, `base_total_amount` in `base_currency`. `upload_rows` (the user must supply the file) and `connect_rows` (connecting the named service fetches it) carry the same month tags. `counts` totals 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 yet, so present the preview as information and do not promise to run it. 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).