Get connector coverage
well_get_connector_coverageRead what a workspace has CONNECTED and what it can connect. This draws nothing on the user's screen.
Use it for every coverage CHECK: a data skill confirming a bank is connected before it measures anything, a step that needs a workspace_connector_id, a health read on a connector the user asked about. Read each row's state and hand the answer back in your own words, in the same turn — there is no card to wait on here, and no acknowledgement to ask for.
⚠️ FOR A CONNECT STEP, CALL well_list_connectors INSTEAD. Same scope arguments, and its result draws the card with the install links and the Continue the user clicks. This tool cannot draw one, so a connect step run here leaves the user with prose and no way to act.
Do NOT read workspace_connectors records to work out connection coverage; this tool is that answer.
To tell whether the user has connected an AI app to Well over MCP, pass kind: "ai_client". A row with is_connected true is a connected AI app. On this one scope the two tools do not answer over the same set: a client Well does not recognise records its connection against a generic row, which this read carries and the install card leaves out. So ask this tool, not well_list_connectors, whether an AI app is connected.
Which rows come back: at most 14 rows, and fewer when the rows are long, kept in this order: connected rows, then rows with an unfinished, disabled or broken connection or a connect attempt that ended, then rows that carry evidence, then the rows install_all_url installs, then the other catalog rows. Connections the page did not hold can be added at the top of the first page (a browse, a slug read, or a search scoped to a kind). omitted_row_count counts every row of the page left out. connection_omitted_count counts the rows with a connection or an ended connect attempt that this result leaves out. It is 0 unless the scope holds more such rows than one result holds. When it is above 0, a kind with no connected row in this result is unchecked: say you could not check it, never that it is missing. A second read of the same scope returns the same rows, so do not repeat it; a read by slug of one tool the user names returns that tool's row. evidence_omitted_count counts the rows of this page that carry evidence and that this result leaves out. The bound keeps the evidence rows in the catalog's order, so the evidence rows returned are the first ones. A cut evidence row is unchecked, not missing: never say that Well has no reason to suggest a tool because its row is absent, and offer no install link for a tool whose row this result does not hold. To check a tool the user names whose row this result does not hold, read that tool by slug: the slug read returns its row, evidence and install link included, so answer about that tool from that row. Paging does not reach a cut row: offset + page_count moves past the whole page. When evidence_complete is true and connection_omitted_count is 0, an omitted row has no connection and no ended connect attempt, so it never changes the state of a kind: kind_states, when the result carries it, states the bank, accounting and invoicing kinds, and any other kind is answered from the rows returned, where a kind with no row that has a connection is missing. When evidence_complete is false on a catalog read (no scope, or a kind of "bank", "accounting" or "invoicing"), Well may not have read the workspace's connections: a kind with no connected row is then unchecked, so say you could not check it, never that it is missing. kind_states gives the state of each kind this read covers ("bank", "accounting" and "invoicing" with no kind, the one kind a kind of "bank", "accounting" or "invoicing" names), worked out from the rows of this workspace. Answer those kinds from it, never from the rows; in a read with one block per workspace, answer each workspace from the kind_states of its own block, next to its workspace_name, never from another block. connected: the tools in sources bring that data in: answer yes and name each one as the tool that brings it (for "bank", the cash movements), also when it is not a bank. connected_incomplete: connected, and each tool in sync_health left data out on its last run: keep going on its data and name it as incomplete beside the figure it feeds, with its summary, which names the records left out (top_target) and why (top_reason) when they are set. connecting: the tools in sources are authorised and connected, and their first data has not arrived yet: say the first sync is running. handshake: the tools in sources are still being authorised, so nothing is connected yet: say the connection is still being set up and offer to wait; never say it is connected or syncing, and never offer a new install for it. error: the tools in error_sources bring that data only once the user repairs them: say so, and do not answer a plain yes. Beside any other state, error_sources still names each tool of that kind owed a repair: name it too. missing: no tool of this workspace brings that kind. unchecked: this result cannot show every connection of that kind (a later page, a cut connection row, or a connection or evidence read that did not finish): say you could not check it, never that it is missing. sources and error_sources then name the tools of that kind this result does show, still connecting or owed a repair: name them, and do not answer a plain yes. sources and error_sources each name at most 3 tools; omitted_source_count, when present, counts the tools they leave out, whose rows name them. When the full lists would make the result too long, both lists come back empty with no sync_health: the state still holds, and the rows name each tool. A read scoped to a pick, to a named tool with no kind, or to upload_surface, storage or ai_client carries no kind_states. A result with no kind_states (one of those reads, or a result whose rows Well could not read) answers each kind from the rows: a kind is connected when a row whose connection_status is "enabled" or "processing" lists it in data_domains, whatever that tool is, so answer yes and name that tool as the one that brings that data in; a row in "need_reconnect" or "error" that lists the kind brings that data only once the user repairs it, so say so and do not answer a plain yes; a row in "to_configure" or "disabled" does not cover the kind. install_all_omitted names the service ids install_all_url does not carry: one link names a bounded number of connectors, and the row bound of this read can cut a row the link would install. This read can leave the rows those ids name out of connectors, so offer no install link for them from this result: their install links come from well_list_connectors, whose card is the connect step. On this read the list names at most 10 ids; install_all_omitted_count counts them all. To read one tool by name, pass slug. Page with offset + page_count.
The rows carry the fields of well_list_connectors, field for field. Its description carries the field reference, and this description does not repeat it, except for one rule. When the user asks what Well reads or changes in a tool, answer from the row's reads and writes only and name only their items, never data_domains, invoice_source, category_id or the tool's name. An empty reads means you do not know yet ("je ne sais pas encore" in French), and an empty writes means Well changes nothing in that tool from the chat. For a tool with is_connected false, give ONE install link, once, raw: the top-level install_all_url when it is non-null, else the row's install_url.
Before a step that runs in the user's own browser (a hand-off to the Well extension), read the top-level extension_installed. Present on a well_get_connector_coverage read only. Whether the person who asks has the Well browser extension in THIS workspace: installed, missing or unknown. The catalog rows never carry the extension, so read this field, never a records query on workspace_connectors. installed: this person opened this workspace in Well with the extension in their Chrome. Well cannot see an uninstall, so a browser hand-off can still stop; report that stop as it happens. missing: nobody has opened this workspace in Well with the extension, so a step that runs in a browser cannot run for this person yet; say so before you hand it off. unknown: Well cannot tell for this caller, for example when another member's extension is on record and this person has none; never say the extension is installed or missing, run the step and report what happens. The answer is for this person in this workspace only: another member's extension never counts as this person's, and the same person can read missing in another workspace.
Before a line that says how a payment in the user's own Chrome goes, read the top-level extension_pays_alone. Present on a well_get_connector_coverage read only. Whether Well may pay alone at the payment page of a task in the asking person's own Chrome, from that person's own pay-alone setting in THIS workspace, the same setting the payment check reads. on: the person chose that Well pays alone; Well then pays alone only under their limits, on a site the workspace trusts, and asks them first above the limits. off: Well asks the person before any payment. unknown: Well could not read it, so make no promise about how the payment goes beyond that nothing is paid before the payment page. A task in a Well browser always asks first, whatever this field says.
A row's move is null when Well is not moving that connection to a company workspace. Otherwise it is { phase, blocker }: the step the move is at and, when the move is parked, what holds it. A row with a move is in progress and never done: say the connection is being moved and takes a while, never that it moved or is ready in the new workspace. When blocker is set, say it is waiting and name the reason in plain words.
Before promising an invoice payment link, read the top-level payment_link_providers. Present on a well_get_connector_coverage read only. The providers (stripe, qonto) whose connection in THIS workspace can make an invoice payment link today, read from what each connection's token can reach. A connected, synced row that is missing here cannot make a link: never promise one for it. An absent field means the read did not run, which is not a provider that can make a link.
Before telling the user a pasted link, page, or resource on another product is out of reach ("I can't access that", "that's outside my reach", "only an admin there can do that"), call this read and check whether a connected connector could plausibly act on it. Match by the PRODUCT the link belongs to, not the raw hostname — a link on a subdomain like docs.superhuman.com or id.superhuman.com may still belong to a connector named "Superhuman Docs"; do not rule one out just because its display name and the URL's host look unrelated. If a plausible match exists, call well_list_connector_tools for it before deciding whether it actually covers the request. Only tell the user the request is out of reach after this read and finding no connector that could act on it.
Well never creates a payment card. Creating a payment card (a virtual card, a single-use card, a card with a spending cap) is not something Well does. Before you say so, when a bank is connected, read its tools with well_list_connector_tools, and never promise a card that no tool can create. Say in one line that Well cannot create the card, and that the person creates it in their bank's own app. Then offer what Well can do with the bank's data.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Name search across the full catalog (e.g. a specific bank). With a `kind` of "bank", "accounting" or "invoicing", the first page also carries the tools of that kind the workspace already has. Omit for the curated view, which lists the tools with evidence first. | |
| kind | No | Scope the card server-side. Three financial domains: "bank" (every bank and neobank, including the long tail of open-banking institutions, plus the platforms that hold an account like Qonto and Pennylane — never a payroll or billing tool that merely reports transactions), "accounting", and "invoicing". Plus two scopes the server resolves from display categories rather than from a financial domain: "upload_surface", the places invoices ARRIVE (mailboxes, messaging apps, file drives), and "storage", the drives Well FILES INTO (Google Drive, Dropbox, OneDrive). The last two are opposite directions on the same drives, so a workspace can hold both connections and each is offered on its own card. And "ai_client", the AI apps that read Well over MCP (Claude, Codex, the Well CLI and the like): read it to tell whether any AI app is connected. Its rows carry no install_url, since an AI app connects from its own settings. Use this for a connect-a-bank, a connect-where-invoices-arrive or a connect-where-Well-files step instead of filtering the default view yourself. Omit for every connectable connector. | |
| slug | No | Exact connector slug: resolves the ONE named connector, of any kind (e.g. "notion" for a connect-Notion request). Use it when the request names a single connector, instead of `q` which name-searches. With a `kind` of "bank", "accounting" or "invoicing" (e.g. slug "pennylane" with kind "accounting"), the result also carries the tools of that kind the workspace already has, so one read answers "this tool, plus what I already have". An unknown slug returns an empty list; retry with `q` on the name then. Cannot be combined with `q`, `from_selection`, `counterparty_ids`, or any other `kind`. | |
| limit | No | Max connectors to return (1-100, default 50). | |
| slugs | No | Exact connector slugs, one per tool the person named in one request (e.g. ["qonto", "pennylane"] for "connect Qonto and Pennylane"): resolves each named connector, and the result carries one `install_all_url` that installs every one of them that is not connected yet, in one browser tab. The card lists every named connector together, each one not connected yet ticked when the call also passes `intent: "connect"`. Use it instead of one call per tool when the request names two to 10 tools. A slug that matches nothing adds no row and no error, so compare the rows with the slugs you sent: your connect instructions say what to do for a named tool the read missed. Cannot be combined with `slug`, `q`, `kind`, `from_selection` or `counterparty_ids`. | |
| intent | No | "describe", with `slug` or `slugs` only: the person asked what Well does in the named tools, or whether Well can connect to them, and did not ask to connect them. "connect" changes nothing on this read, which ticks no tool. | |
| offset | No | Number of connectors to skip, for paging (default 0). | |
| country | No | The company's country as an ISO 3166-1 alpha-2 code (e.g. "FR"). When set, the connectors that serve that country sort first, then the ones that serve its region, then the rest — the order only, no row is dropped. A bank brand sold in several countries (Revolut, Wise) shows that country's own connector, so pass the member's country when they name a bank. Use it on a connect-a-bank or a connect-an-accounting-tool step so the banks or accounting tools that fit the company appear first; take it from the workspace identity's country. Omit when the country is unknown: on a connect-a-bank step Well then ranks for the member's own country when it can read one, and otherwise by the banks the most Well workspaces connect, and the result says `country_unknown`. | |
| suggest | No | The tools you suggest from something the person told you, which only you can read (their notes, your memory of them, what they said earlier): each a catalog service_id and a one-line reason in the person's language ("You told me you bank with Qonto"). Those rows gain note evidence, rank with the other tools that have evidence, and carry your reason as their suggestion_reason. Never name a tool here from a guess, an email domain or a category alone. At most 10. | |
| workspace_id | No | Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which. | |
| from_selection | No | Scope the card to the connectors behind the counterparties the user picked on the missing-invoices card in this conversation, each installable one pre-checked. Use it for the connect step that FOLLOWS a vendor pick. It returns those vendors' connectors and NOTHING else: a picked connector that brings no invoices in is dropped, and no accounting or invoicing tool the user did not pick is offered here: that offer is its own step, scoped with `kind`. Cannot be combined with `q` or `kind`: those name a catalog to browse, and this names a set already decided. Returns an empty list when this conversation holds no pick for this workspace, or when no picked counterparty matched a connector. | |
| 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. | |
| 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. | |
| counterparty_ids | No | Scope the card to the connectors behind these counterparties, copied from the `company_id` of the missing-invoices rows. The explicit form of `from_selection`, for a caller holding the picked ids itself instead of a card click recorded in this session: it resolves the same connectors and filters them the same way. Passing counterparty_ids alone already scopes the card to the pick — from_selection is not needed alongside it; it cannot be combined with `q` or `kind`. | |
| include_unsent_counts | No | Add the top-level `unsent_document_counts`: every tool Well forwards this workspace's documents to, each with how many documents it has not received yet. That array is the whole answer — it holds every one of the workspace's outbound connections, whatever catalog page was requested, and the rows carry no count at all. Off by default, because it costs an extra read. The figure is the workspace's whole backlog, not a period's. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | ||
| limit | No | The page size that was REQUESTED. The catalog may return fewer. | |
| scope | No | What this result is a list OF: the requested kind, the picked vendors' connectors, or the curated catalog when neither was asked for. The card words itself from this, so it never describes the rows as a domain that was not requested. | |
| total | No | Every connector matching the query, across all pages — NOT the length of `connectors`. | |
| offset | No | How many catalog rows this page skipped. | |
| success | Yes | ||
| row_count | No | How many rows this result returns, prepended rows included; omitted_row_count counts the rest of the page. Not a paging cursor: page_count is. | |
| connectors | No | ||
| page_count | No | The catalog page's own length, and the ONLY safe paging cursor: advance by `offset + page_count`. `connectors` can be longer (connections the page did not hold can be prepended on the first page) or shorter (omitted_row_count rows left out), so never page by the array's length. | |
| kind_states | No | kind_states gives the state of each kind this read covers ("bank", "accounting" and "invoicing" with no kind, the one kind a kind of "bank", "accounting" or "invoicing" names), worked out from the rows of this workspace. Answer those kinds from it, never from the rows; in a read with one block per workspace, answer each workspace from the kind_states of its own block, next to its workspace_name, never from another block. connected: the tools in sources bring that data in: answer yes and name each one as the tool that brings it (for "bank", the cash movements), also when it is not a bank. connected_incomplete: connected, and each tool in sync_health left data out on its last run: keep going on its data and name it as incomplete beside the figure it feeds, with its summary, which names the records left out (top_target) and why (top_reason) when they are set. connecting: the tools in sources are authorised and connected, and their first data has not arrived yet: say the first sync is running. handshake: the tools in sources are still being authorised, so nothing is connected yet: say the connection is still being set up and offer to wait; never say it is connected or syncing, and never offer a new install for it. error: the tools in error_sources bring that data only once the user repairs them: say so, and do not answer a plain yes. Beside any other state, error_sources still names each tool of that kind owed a repair: name it too. missing: no tool of this workspace brings that kind. unchecked: this result cannot show every connection of that kind (a later page, a cut connection row, or a connection or evidence read that did not finish): say you could not check it, never that it is missing. sources and error_sources then name the tools of that kind this result does show, still connecting or owed a repair: name them, and do not answer a plain yes. sources and error_sources each name at most 3 tools; omitted_source_count, when present, counts the tools they leave out, whose rows name them. When the full lists would make the result too long, both lists come back empty with no sync_health: the state still holds, and the rows name each tool. A read scoped to a pick, to a named tool with no kind, or to upload_surface, storage or ai_client carries no kind_states. A result with no kind_states (one of those reads, or a result whose rows Well could not read) answers each kind from the rows: a kind is connected when a row whose connection_status is "enabled" or "processing" lists it in data_domains, whatever that tool is, so answer yes and name that tool as the one that brings that data in; a row in "need_reconnect" or "error" that lists the kind brings that data only once the user repairs it, so say so and do not answer a plain yes; a row in "to_configure" or "disabled" does not cover the kind. | |
| 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. | |
| country_unknown | No | Present on a bank list when no country is known for this member at all, so the banks are ranked by how many Well workspaces connected them. Ask which country the member's bank is in, then call again with `country`. | |
| install_all_url | Yes | One link that installs every installable connector in this result. Null when the result offers nothing to install, or when its scope names a set the reader has not chosen. When it is non-null it is the ONLY install link the answer offers — do not list the rows' own install_url beside it. When it is null, the rows' own install_url is the offer instead. | |
| 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. | |
| evidence_complete | No | False when Well could not read every source of evidence for this workspace. A row with empty `evidence` is then UNCHECKED, not clean: say you could not check, and never say there is no sign yet. True or absent means every source was read. Only a catalog read (no scope, or a `kind` of `bank`, `accounting` or `invoicing`, with or without `q` or `slug`) reads evidence: the picked-vendor (`from_selection`, `counterparty_ids`), `upload_surface`, `storage` and `ai_client` scopes read no workspace evidence. A row holds only a note you passed in `suggest`, otherwise empty `evidence`. These scopes always report false. | |
| omitted_row_count | No | How many rows of this catalog page the result leaves out, every group included. When evidence_complete is true and connection_omitted_count is 0, an omitted row has no connection and no ended connect attempt, so it never changes the state of a kind: kind_states, when the result carries it, states the bank, accounting and invoicing kinds, and any other kind is answered from the rows returned, where a kind with no row that has a connection is missing. When evidence_complete is false on a catalog read (no scope, or a kind of "bank", "accounting" or "invoicing"), Well may not have read the workspace's connections: a kind with no connected row is then unchecked, so say you could not check it, never that it is missing. | |
| ranked_for_country | No | Present on a bank list when the call named no country and the workspace has none: the country Well read from the member (their phone number on WhatsApp, else their sign-up, address or bank account) and ranked the banks for. Never say where it came from. If the member's bank is in another country, ask once and call again with `country`. | |
| resolved_workspace | No | The workspace that answered, when the caller named none and the token authorizes several. | |
| extension_installed | No | Present on a `well_get_connector_coverage` read only. Whether the person who asks has the Well browser extension in THIS workspace: `installed`, `missing` or `unknown`. The catalog rows never carry the extension, so read this field, never a records query on workspace_connectors. `installed`: this person opened this workspace in Well with the extension in their Chrome. Well cannot see an uninstall, so a browser hand-off can still stop; report that stop as it happens. `missing`: nobody has opened this workspace in Well with the extension, so a step that runs in a browser cannot run for this person yet; say so before you hand it off. `unknown`: Well cannot tell for this caller, for example when another member's extension is on record and this person has none; never say the extension is installed or missing, run the step and report what happens. The answer is for this person in this workspace only: another member's extension never counts as this person's, and the same person can read `missing` in another workspace. | |
| install_all_omitted | Yes | install_all_omitted names the service ids install_all_url does not carry: one link names a bounded number of connectors, and the row bound of this read can cut a row the link would install. This read can leave the rows those ids name out of connectors, so offer no install link for them from this result: their install links come from `well_list_connectors`, whose card is the connect step. On this read the list names at most 10 ids; install_all_omitted_count counts them all. | |
| unfinished_connects | No | Connect attempts in this workspace the person has not been told about yet, newest first. `outcome` is `stopped` (the person closed the connect before it finished), `timed_out` (nobody finished it within the hour), or `still_connecting` (it started within the last 10 minutes and is still open; past that it is no longer listed). An empty array means there is nothing to tell; an absent field means nothing was read. Name a tool by its `name`. For each entry, say one short line in the reply: on `stopped` or `timed_out`, offer to connect it again or to skip it for now; on `still_connecting`, offer to wait or to skip it for now. Once the reply says the lines, call `well_mark_connects_told` with the `workspace_connector_id` of each entry it said, so a later read does not repeat them. An entry the reply did not say stays unmarked and comes back on the next read. | |
| conversation_id_note | No | Present only when the server opened a fresh lane, stating that no choice recorded earlier was read. | |
| extension_pays_alone | No | Present on a `well_get_connector_coverage` read only. Whether Well may pay alone at the payment page of a task in the asking person's own Chrome, from that person's own pay-alone setting in THIS workspace, the same setting the payment check reads. `on`: the person chose that Well pays alone; Well then pays alone only under their limits, on a site the workspace trusts, and asks them first above the limits. `off`: Well asks the person before any payment. `unknown`: Well could not read it, so make no promise about how the payment goes beyond that nothing is paid before the payment page. A task in a Well browser always asks first, whatever this field says. | |
| 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. | |
| evidence_omitted_count | No | evidence_omitted_count counts the rows of this page that carry evidence and that this result leaves out. The bound keeps the evidence rows in the catalog's order, so the evidence rows returned are the first ones. A cut evidence row is unchecked, not missing: never say that Well has no reason to suggest a tool because its row is absent, and offer no install link for a tool whose row this result does not hold. To check a tool the user names whose row this result does not hold, read that tool by slug: the slug read returns its row, evidence and install link included, so answer about that tool from that row. Paging does not reach a cut row: offset + page_count moves past the whole page. | |
| payment_link_providers | No | Present on a `well_get_connector_coverage` read only. The providers (`stripe`, `qonto`) whose connection in THIS workspace can make an invoice payment link today, read from what each connection's token can reach. A connected, synced row that is missing here cannot make a link: never promise one for it. An absent field means the read did not run, which is not a provider that can make a link. | |
| unsent_document_counts | No | Every tool this workspace forwards documents to, each with the documents it has not received yet, biggest backlog first. Present only when `include_unsent_counts` was set. THIS IS THE ONLY PLACE THE BACKLOG IS REPORTED: it is not a page, it carries the workspace's whole set of outbound connections whether or not the requested catalog page holds their rows, and the catalog rows carry no count. An empty array means the workspace forwards to nothing; an absent field means nothing was measured. `unsent_document_count_is_upper_bound: true` means a document filter applies to that connection, so the count is a maximum and reads as `up to <n>`. Every count is read off Well's own forward record, so it measures what Well wrote down rather than what the tool confirmed. Name a tool by its `name`. An entry reading `0` is a tool that is up to date: say nothing about it. | |
| picked_vendors_filtered | No | How many of the picked vendors' connectors were dropped for bringing no invoices in. Present on the `picked_vendors` scope only. Above zero means the card is SHORTER than the pick: say that those vendors' tools cannot deliver an invoice, rather than letting the gap read as a pick the user never made. | |
| connection_omitted_count | No | connection_omitted_count counts the rows with a connection or an ended connect attempt that this result leaves out. It is 0 unless the scope holds more such rows than one result holds. When it is above 0, a kind with no connected row in this result is unchecked: say you could not check it, never that it is missing. A second read of the same scope returns the same rows, so do not repeat it; a read by slug of one tool the user names returns that tool's row. | |
| install_all_omitted_count | Yes | How many service ids install_all_url does not carry, the ids install_all_omitted leaves out included. |