well_list_receipt_candidates

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

List the payments a stored receipt may belong to, so the member picks the right one. Call it when the member asks to attach a receipt or an invoice they sent (« rattache-le », "attach it"). It writes nothing. The `document_id` is the id of the stored document the member sent. You hold it in the "Attached Document" block of the turn that carries the file. On a later turn (« rattache-le »), take it from the first row of the "Documents this conversation received earlier" block: those are the files this conversation sent, newest first. If you hold no `document_id` from either block, ask the member which document they mean. Never guess an id, and never take one from a query on the `documents` records: that table also holds files a connector synced and files other members sent. Always name the receipt the result reads (`receipt`: supplier, amount, date) in your line, and when it does not match what the member described, say so before anything else. Read `outcome` first. It decides the whole reply: - `candidates`: 1 to 3 payments fit (for example two payments of the same amount on the same day, or matches Well is not sure of). Show each payment (date, payee, amount; add the time or the card when two lines would read the same) as a numbered choice, then one last choice for none of them (`none_option`). Ask the member to answer with the number. Never pick a payment yourself, even when only one is listed. On WhatsApp the numbered list is drawn under your text, and it names the receipt: write one short line and do not repeat the list. - `no_candidates`: no payment fits yet. Say the receipt stays in Well as a document and that Well attaches it on its own when its payment appears. Ask nothing. - `already_linked`: the receipt already sits on `linked_transaction` (or a sure match names it and Well attaches it within the hour). Say it is already attached and name that payment. Do not call `well_link_receipt_to_transaction`. - `extraction_pending`: Well is still reading the document. Say so in one line and that you will look again in a moment. Ask nothing, list nothing, and call nothing else for it. - `ask_document_kind`: Well read no receipt or invoice in this document. Ask the member, in one numbered question, what it is: a receipt, a supplier invoice, or something else (`document_kinds`, in that order). Do not list payments. When the member answers with the number of a payment, call `well_link_receipt_to_transaction` with this `document_id` and that payment's `transaction_id`. That answer is the member's consent: ask for no other confirmation. When the member picks the last choice (none of them), call nothing: the receipt stays a document, and Well attaches it when a confirmed match appears. A payment that already holds another document, or that another invoice already settles, is never listed. Each candidate carries `source`: `provisional_match` (the matcher's unsure match), `review_candidate` (listed by the open reconciliation review) or `amount_and_date` (same amount and currency, paid near the receipt date). The order is the ranking; keep it. **`success: false` means the read failed.** No payment list exists, so never say the receipt has no payment. When the token authorizes one workspace, call this directly — no workspace call is needed first. When it authorizes several, this read will not guess which one you mean: pass `workspace_id` on the call.