deploy-agents

name	deploy-agents
requires	["define-workspace","define-period","show-missing-invoices"]
description	Preview what Well would fetch for the vendors the user picked — which agents would run, over which counterparties and transactions, which rows need a manual upload, and which providers need connecting — then hand those vendors to the Well app. Nothing collects anything yet. The preview card gives a checkbox to each vendor the collect link names, and its primary action opens that link for the portals the user ticked. The Well browser extension collects from those portals, and only after the user starts them on that page. Use when the user asks to fetch, collect, or chase the invoices they are missing, says "launch the agents", "go get those invoices", "deploy the collectors", or when the fetch-missing-invoices flow reaches its last step after the missing rows have been listed and picked. Do not use to run a collection from the chat, to invoke a connector's own actions, to create or edit an invoice, to connect a provider, or to list which invoices are missing in the first place.

Deploy Agents with Well

Purpose

Show what a real invoice fetch would do, before anything is done. Take the vendors the user picked on the missing-invoices card, group them into the agents Well would run — one per provider, with the counterparties and transactions behind each — and state, in the user's language, what would happen: which agents, which rows the user has to upload by hand, which providers are not connected yet. The scope is the user's pick, not everything the period yields.

This skill collects nothing. It and its card start no agent, open no browser session and queue no task. The card's primary action opens the collect link, which names the portals the user ticked. The Well browser extension runs those portals, and only after the user starts them on that page. So the honest sentence is not "the run has started" — it is "nothing has started here, and the collection runs in the browser extension once you start it there". This skill never learns what a run produced. This is the last brick of Well's fetch-missing-invoices flow.

When to use this skill

Use this skill when:

• The user asks Well to fetch, collect, retrieve, or chase the invoices they are missing ("go get those invoices", "can you pull the March receipts from Shopify?").
• The user asks to launch, deploy, or start the agents, or asks what would run.
• The fetch-missing-invoices flow reaches its last step and its missing rows have already been listed and picked.
• The user wants the plan first: "what would you do?", "show me the plan before you run anything".

When not to use this skill

Do not use this skill when:

• The user wants to know which invoices are missing — that is the show-missing-invoices skill, the step before this one; this skill reads that skill's hand-off rather than recomputing it.
• The user wants a fetch result, a downloaded file, or a status update on a running collection — this skill starts nothing and receives nothing back. The collect link its card opens hands the picked portals to the Well browser extension, and the extension's side panel reports the runs. Point the user there instead of promising progress.
• The user wants to connect a provider so it can be fetched from — that is the connect-tools skill.
• The user wants to create, edit, or attach an invoice by hand — those are Well's invoice skills and the Well app, not this one.
• No workspace or no period is pinned — run define-workspace and define-period first.

Inputs

The calling skill or the user provides:

• The show-missing-invoices hand-off — required in practice. Its agent_candidates carry the rows this preview is built from, and its selection plus selection_state carry the vendor pick, as the next bullet says. Without the hand-off, and without the preview tool below, there is nothing to preview: say so, hand off resolution: unavailable, and stop. Never report that state as nothing_to_do — the period may hold plenty to fetch; the preview simply could not be built.
• The vendor selection — the pick the missing-invoices card wrote. Read it from the show-missing-invoices hand-off, which carries it on two fields: selection names the picked vendors, each as its company_id plus its matched_connector_service_id or null, in the order the pick came in; selection_state says what that list means. Route on those identifiers, never on a vendor's display name.
  • written — the pick is recorded. Preview the selection.
  • pending — the card is on screen and nothing is ticked yet. Send the flow back to show-missing-invoices for the click rather than previewing every row.
  • none — the gap list was empty or unavailable, so it held nothing to pick. This is not a missing pick and it never asks for a tick: an empty list resolves nothing_to_do, an unavailable one resolves unavailable. well_list_workspaces' session.selected_counterparties is the resync fallback, for a click the hand-off missed and for a run that reaches this skill with no hand-off at all. That field is null until a pick is recorded, and each entry under its counterparties is a company_id plus a matched_connector_service_id or null. It also names the workspace its company ids belong to, so a pick whose workspace_id is not the pinned one is not this pass's pick. A pick is trustworthy only for the gap-list card now on screen. A pick taken on an earlier card — before a fresh gap-list read, or before a change of months — names rows the user is no longer looking at, so it is not this pass's pick either. Send the flow back to show-missing-invoices for a fresh tick rather than previewing on it.
• workspace_id — required. Comes from define-workspace, or from the session pin (' ) used silently only when THIS conversation established it. Hosts share one MCP session across conversations, so a pin this conversation never made is another conversation's leftover: ignore it, never mention it, and run instead. Never resolved or asked for in text here.

Several workspaces. A multi-workspace run is driven by the caller: the pin plus the session's workspace_queue (read from well_list_workspaces' session block) name the sequence, and this skill always works on the currently pinned workspace only. The caller re-pins with well_switch_workspace({ workspace_id }) between passes; each pass gets its own preview, and nothing is merged across two entities.

Tooling

Runs over Well's MCP server (https://api.wellapp.ai/v1/mcp, streamable HTTP). Two read-only tools are involved. The preview tool is optional, and the session read is a resync fallback:

• well_preview_invoice_fetch — when it is present in your toolset. Input: workspace_id explicitly, as on every well_* call, and no periods argument — omitted, the server uses the period selection the user's click (or define-period) already wrote. An error comes back only when no selection exists yet: run define-period, then re-call. A period pair is passed explicitly only on an older server that holds no session selection — the degrade path, never the default. Output: the period fields — periods_requested, periods_covered (each month as calendar_year, calendar_month and period_label, oldest first) and months (each month's own counts) on every success, plus calendar_year, calendar_month, fiscal_year, fiscal_period and period_label only when the selection held exactly one month, so a selection spanning several months carries no single label to quote — agents (each with provider_name, provider_id or null, domain — the provider's bare host, e.g. aws.amazon.com — and url — the portal address the catalog holds, which domain reduces to its host; both are null when unmatched or absent from the catalog, and both are display only — logo_url, counterparties — each name, its own month (calendar_year, calendar_month, period_label), tx_count, base_total_amount and suggested_route — connect_routed_counterparties, tx_count, and base_total_amount or null), upload_rows and connect_rows (their rows carry the same month tag), counts, collect_url — the collect link for the previewed portals — collect_url_omits — the portals a large window pushed past that link's ceiling, present only when some were left out — with beside it, — the currency every is stated in — , , and . It is a read: it computes the plan and returns it. Carry , , and through to your hand-off — is the identifier the link names and a run routes on, only labels the portal on screen, tells a scoped result from a period-wide one, and says how far the categorized data reaches.

Never call a tool that changes anything. Specifically: no well_invoke_connector_tool, no well_create_*, no well_update_*, no well_delete_*, no connector action of any kind. This skill reads or derives, and it never writes. It does not re-pin the session either: on a multi-workspace run the caller calls well_switch_workspace between passes, as the Inputs section says.

Composed skills. Three Well skills own the steps this skill must not 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 call here carries.
• define-period — resolves the month or fiscal period and writes the selection server-side, which is what makes the periods argument unnecessary on the preview call.
• show-missing-invoices — lists the transactions with no invoice for that period, on the card the user picks the vendors to chase from. Supplies the agent_candidates this preview is built from, and is the only source of the preview on the tool-absent path. Its hand-off carries the pick as well — selection and selection_state — which is what keeps this step from previewing a vendor the user never ticked.

All three ship with the well-skills plugin. None has an inline fallback here: this skill resolves no workspace of its own, guesses no month, and never rebuilds the gap list, so when one is absent the workflow runs that skill instead of working around it.

Workflow

Call each list or read tool once per step. The widget cards refresh themselves — never re-call a tool just to check progress.

1. Tell a missing server apart from a missing tool. Two different states, two different answers:

   • No well_* tool at all in your toolset → the Well MCP server has not been added to this host. Tell the user to add it at https://api.wellapp.ai/v1/mcp, then fall back to the hand-off if you have one.
   • well_* tools are there but well_preview_invoice_fetch is not → the tool simply does not exist in this host yet. Say nothing about it; take the tool-absent path in step 3. This is the normal state today, not a fault to report. A run derived entirely from the show-missing-invoices hand-off calls nothing, so neither check blocks it.

2. Confirm the workspace, the period, and the pick. Require workspace_id — from the caller, or a session pin used silently when this conversation established it. Missing workspace, or a pin left by another conversation → run define-workspace and never reuse or mention that leftover pin. If the preview tool answers that no period selection exists yet, run define-period (its picker writes the selection) and re-call — never pin either one here and never guess a month. Require the vendor pick too, and take it from the show-missing-invoices hand-off. selection_state: written → preview its selection. pending → run show-missing-invoices so its card takes the click, and preview nothing meanwhile. none → the list held nothing to pick, so resolve nothing_to_do on an empty list and unavailable on an unavailable one, and ask for no tick no card can take. With no hand-off, or to catch a click the hand-off missed, read well_list_workspaces' session.selected_counterparties instead: a null field, or one naming a workspace other than the pinned one, reads as pending. Pass workspace_id explicitly on any call you make.

3. Build the preview, and keep it to the pick.

   • Tool present → call well_preview_invoice_fetch({ workspace_id }) — no periods argument; the server reads the clicked selection — and use its agents, upload_rows, connect_rows, counts, scoped_to_selected_counterparties and as they come, , and included. Do not recompute or re-sort them. : the server filtered every route to the recorded pick, for the months the pick was made against. Say the plan covers the picked vendors only for those months, and that a month of the window the pick never covered is covered in full. Narrow nothing further. One agent covers one supplier portal however many months the selection held, so never split or restate an agent per month: each counterparty under it names its own month, carries each month's own route counts, and a selection spanning several months is named from rather than under one label the result does not carry.

Output requirements

Return:

• One line per agent, in the user's language, each with the provider, the count, and the fact that nothing has started yet. Above five agents, the five largest by invoice count plus one line for the rest.
• One line for the counterparties to upload by hand, and one line for the counterparties still to connect — counterparty rows, one per month, or a distinct-vendor count the line names as such. Both lines appear even when the count is zero. A third line, only when unmatched_rows is non-zero, for the transactions whose provider Well could not identify. A fourth, only when an agent carries no provider_id or the tool listed it in collect_url_omits, for the vendors the collect link cannot name. On nothing_to_do the single nothing-to-fetch sentence replaces all of them.
• One line stating that the preview covers categorized expense transactions only.
• One line stating what the plan covers — the picked vendors only, for the months the pick was made against, when scoped_to_selected_counterparties is true; the whole period when that flag is absent and no hand-off narrowed the result.
• One line asking the user to confirm the vendors and deploy from the card — or, where no card is drawn, carrying the collect link itself.
• One plain sentence stating that no agent has started here, no task is queued and no browser session is open, and naming where a collection does start — the collect page hands the picked portals to the Well browser extension, whose side panel reports the runs.
• The hand-off, kept for the calling flow and never printed: workspace_id — the one this skill ran on, the same value every hand-off in this flow opens with; the period — the single-month fields when the result carried them, periods_covered plus the per-month months counts when it did not, so the caller is never told one month for a preview spanning several; run_mode: preview; nothing_launched: true; selection — the picked vendors as the hand-off carried them, company_id plus matched_connector_service_id or null, so a later step routes on identifiers and never on a vendor's name; the agents — each with its provider_name, provider_id, its domain or null, its counterparties (name, tx_count, base_total_amount), its summed tx_count, and its summed amount or null; upload_rows, connect_rows, and ; — the collect link when the tool returned one, else null; — true when the tool scoped the result to the pick, absent otherwise; the — categorized expense transactions only, plus the tool's when it ran; and — , , or . names how this skill ran and is always ; it mirrors the tool's under a different key, because upstream means a row's badge. is the identifier the collect link names and a run dispatches on, and only labels the portal on screen; is null only when neither the tool nor the hand-off carries one. counts the group's transactions, which no agent covers. On , is empty and every row count is zero or empty. On — neither the preview tool nor a hand-off was there to build a plan from — only , the period, and are kept, and no counts are claimed. These keys are reasoning vocabulary for you and the calling flow; the hand-off travels as plain conversation, not as a data block.

Do not return:

• A yaml or JSON block, or any fenced code block — the hand-off travels as plain conversation.
• Any claim that an agent ran, is running, or produced a result — including a percentage, a file, or an ETA — any claim that this skill or the collect page knows a run's outcome, and any claim that a link the host refused started a run.
• The row detail restated under the preview card that already shows it.
• A null amount printed as a number, or amounts summed across currencies.
• An agent for a provider that is not in the preview or in agent_candidates.
• The same vendor reported as two gaps, or the connect count added to the agent count, when the preview lists that counterparty on both routes.
• An agent named for a provider Well never matched — the "unknown" group is not an agent.
• A vendor promised to the run when its provider_id is null or the link left it out, or a collect link you built yourself.
• A selection edited from the user's sentence instead of a fresh pick on the missing-invoices card, or a pick taken on an earlier gap-list card carried into this preview.
• A period-wide result described as the pick when scoped_to_selected_counterparties is absent.
• categorize-counterparties offered as a way to widen the preview — it writes the vendor company's industry labels, and this plan is bounded by transaction categorization.

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 preview cards from one that did not. Write an answer that stands on its own and let the cards add to it where there are some. State the agents 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.

Quality checks

Before finishing, verify:

• No write tool was called: no well_invoke_connector_tool, no well_create_*, no well_update_*, no well_delete_*, no connector action.
• workspace_id came from the caller, or from a session pin this conversation established — no leftover pin from another conversation was reused or mentioned. The period came from the server-held selection (the preview call carried no periods argument), and neither was resolved or guessed here.
• The preview came from well_preview_invoice_fetch when it exists, and from the show-missing-invoices hand-off's agent_candidates when it does not — never from a guess about which providers a workspace uses.
• The pick was in hand before anything was previewed: the show-missing-invoices hand-off's selection, matched on company_id, with selection_state: pending — or a pick belonging to an earlier gap-list card — sent back to show-missing-invoices for a fresh click, and selection_state: none resolved as an empty or unavailable list rather than asked for again.
• The scope line came from scoped_to_selected_counterparties: the picked vendors only, for the months the pick was made against, when it was true; the whole period when it was absent and no hand-off narrowed the result.
• A preview spanning several months named every month from periods_covered, quoted no single period_label (the result carries none then) and composed no range label, kept one agent per portal across the months, and handed off periods_covered and the per-month months counts.
• One line per agent, in the user's language, each saying nothing has started, written whatever the host drew and never expanded into the row detail the card carries.
• The turn ended on the card with one line asking the user to confirm the vendors and deploy — or, where no card was drawn, carrying the collect link exactly as collect_url returned it, its required workspace parameter intact, or the workspace link — with no parameter added, edited or removed on either.
• A counterparty the preview listed under a portal and in connect_rows was reported once, as one gap with two routes, and the two lists were never added together.
• On a previewed run the upload line and the connect line are both present, even at zero, each counted in counterparty rows — one per month — or in a distinct-vendor count the answer names as such, plus an line of its own when that count is non-zero. On none appear.

Examples

Example request

The fetch-missing-invoices flow calls deploy-agents with workspace_id of Acme SAS, the March 2026 selection already written by the user's click on the period card, and the show-missing-invoices hand-off, its agent_candidates covering Shopify (3 transactions, 1 counterparty) and Free Pro (2 transactions, 1 counterparty), with no "unknown" group, plus 4 upload rows on four other counterparties and one connect row on an unconnected Stripe account. The session holds a pick of three vendors for this workspace: the Shopify counterparty, Free Pro, and Stripe. The user writes in French. well_preview_invoice_fetch is not in the toolset.

Expected behavior

Keep the candidates whose company_id is in the session's pick, derive the preview from them, and call nothing. Answer:

Agent prêt pour Shopify — 3 factures (rien n'est encore lancé) Agent prêt pour Free Pro — 2 factures (rien n'est encore lancé) Aucune ligne à téléverser à la main parmi les fournisseurs retenus. 1 ligne dépend de Stripe, qui n'est pas encore connecté.

Ce plan ne couvre que les dépenses déjà catégorisées de la période : ce qui ne l'est pas encore n'y apparaît pas.

Aucun agent n'a démarré ici, aucune tâche n'est en file, aucune session de navigation n'est ouverte. La collecte se lance depuis l'extension Well, une fois que vous la démarrez sur la page de collecte. Ouvrez l'espace de travail dans l'app Well — <well-app-base-url>/workspaces/<workspace_id> — pour voir les mêmes lignes manquantes. Ces chiffres comptent les transactions sans facture, pas les factures déjà récupérées.

Then keep the hand-off — workspace_id, run_mode: preview, nothing_launched: true, the selection, each agent's provider_id (the group's matched_connector_service_id, or null), collect_url: null, coverage_note, resolution: previewed — and hand back to the caller. Nothing more is printed. The upload line reads zero because no upload row names a picked counterparty, and it still appears at zero. Leave the hand-off's counts.upload out of the answer: it is a period-wide number with no counterparty behind it, so no pick-scoped line can be built from it. The hand-off carries no scoped_to_selected_counterparties: the tool never ran, and the pick was applied here.

Example request

Same flow, in a Claude Desktop session where well_preview_invoice_fetch is available.

Expected behavior

Call well_preview_invoice_fetch({ workspace_id }) — the server reads the clicked selection. The result carries scoped_to_selected_counterparties: true, so it already covers the picked vendors only. The preview card renders the vendors the link names with their checkboxes, its select-all, its Preview badge and its Deploy action. Do not restate the rows. Say one line per agent — provider, count, nothing started yet — then the upload line, the connect line, the line saying the plan covers the picked vendors only, the coverage line carrying the tool's hints, one line asking the user to confirm the vendors and deploy, and the plain sentence that nothing has started here and the extension runs the collection once the user starts it on the collect page. Carry each agent's provider_id and domain, plus the envelope's collect_url and scoped_to_selected_counterparties, into the hand-off. End the turn there.

Example request

"Great, now actually run them."

Expected behavior

Say plainly that nothing runs from the chat. Deploy on the card opens the collect link for the vendors still ticked, and the Well browser extension collects from those portals once the user starts them on that page. Where no card is drawn, give the collect link from collect_url, or <well-app-base-url>/workspaces/<workspace_id> when the preview carried none. Do not call any tool, do not promise a run from the chat, and do not re-emit the preview as though it were a finished run.

Example request

Same flow, tool absent, and the hand-off's agent_candidates hold two groups: Amazon with three counterparties (5 transactions) and "unknown" with two counterparties (2 transactions).

Expected behavior

Build one agent, for Amazon. The "unknown" group is not an agent: Well matched no provider for those rows, so nothing can be dispatched for them. Its 2 transactions become unmatched_rows, on a line of their own rather than folded into upload_rows: "Agent ready for Amazon — 5 invoices (nothing started yet)", then the upload line, then "2 transactions have no provider Well could identify — no agent covers them", then the connect line, the coverage line, the deploy line, and the plain sentence that nothing has started here. Never write "Agent ready for unknown".

Example request

The flow calls deploy-agents for a period whose rows all already have an invoice attached — agent_candidates is empty, selection_state is none, and there is nothing to upload or connect.

Expected behavior

Return resolution: nothing_to_do: "Nothing to fetch for March — every categorized expense transaction already has its invoice, and spend that is not categorized yet cannot appear here. No agent has started, no task is queued, no browser session is open." The upload line, the connect line and the deploy line are dropped: there is nothing to upload, nothing to connect and nothing to collect. Keep an empty agents list with the coverage_note set, and hand back. Do not offer categorize-counterparties as a way to uncover more: it labels the vendor companies, not the period's transactions. Do not invent an agent, and do not offer to run one anyway.

Example request

The flow reaches this skill with no pick recorded — the missing-invoices card is on screen and the user has ticked nothing yet.

Expected behavior

Preview nothing. The hand-off carries selection_state: pending, which is a tick still to come and not an empty list. Say the pick comes first, run show-missing-invoices so its card takes the tick and the Continue click, and come back once its hand-off carries selection_state: written. Do not preview every vendor of the period as a stand-in for the pick.