List member candidates
well_list_member_candidatesList the teammates a workspace can invite, exactly as the Well app's invite card shows them. Use it before well_invite_members, and for "who can I invite to this workspace?".
Returns candidates, each with person_id, name, email, avatar_url, a state (active already has access, pending was invited and has not accepted, not_member can be invited), and a source (detected shares the workspace owner's corporate email domain, provided was named in person_ids or resolved from the assigned gap owners). Never invite a candidate whose state is active. Alongside them it returns targets — this workspace plus any workspace group you belong to, each an option for where the invite lands — roles (admin or member, with a hint), and me_person_id so you never offer to invite the caller. On a demo workspace, which holds sample data, candidates and targets are empty and refusal_reason is DEMO_WORKSPACE: tell the user to invite the team in their own workspace.
Three ways to source the candidates:
Default: the detected same-domain teammates who hold no membership.
person_ids: resolve specific people you already hold the ids for, with their membership state. Setinclude_detectedfalse to return only those.from_assigned_gaps: true: resolve the owners of the settled expense transactions still missing a supplier invoice for the period, server-side, with their membership state — the invite step of a close or fetch flow uses this so it never depends on remembering who was assigned on the owner card. It returns only those owners (the detected teammates are omitted). Name the period ONE way —{ calendar_year, calendar_month }or{ fiscal_year, fiscal_period }— or name no period to use the months selected on the period card this session. Every month must have ended.
⚠️ This tool draws its invite card on EVERY call, the empty one included. When the user asks who they can invite, call it directly: the card, with its contact search, is the answer. But in the invite step of a close or missing-invoice flow, where you read with from_assigned_gaps: true only to find out whether an owner of the period's gaps still needs an invitation, call well_get_worklist_status({ worklist: "gap_owners_to_invite" }) first, with the same period you would pass here or none for this conversation's selected months. It draws nothing, and its count is how many of those owners are pending or not_member. Make the from_assigned_gaps call only when that count is above zero. A solo workspace whose owner assigned the gaps to themselves answers 0: nobody is left to invite, so no card is drawn. An ABSENT count is not a zero: success: false means the probe could not read the owners.
⚠️ WAIT ON THE CARD IN THE TURN THAT DREW IT. Write your one line for the user FIRST, then call well_wait_for_selection({ kind: "invite_ack" }), which this result's next_step also states. The card's own footer sends the invitations and writes the acknowledgement, so never call well_invite_members yourself after a click. The outcome the click carries says which button it was: "done" sent the invitations, "keep_for_later" set the step aside. Both end the step.
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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| person_ids | No | Person ids to resolve with their membership state (the `provided` source). | |
| fiscal_year | No | Fiscal year (the calendar year the workspace's fiscal year STARTED in). `from_assigned_gaps` only. | |
| 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. | |
| calendar_year | No | Calendar year, e.g. 2026. `from_assigned_gaps` only. | |
| fiscal_period | No | Fiscal period, 1-12. `from_assigned_gaps` only, paired with `fiscal_year`. The adjustment period (13) is refused. | |
| calendar_month | No | Calendar month, 1 = January … 12 = December. `from_assigned_gaps` only, paired with `calendar_year`. | |
| 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. | |
| include_detected | No | Omit the detected same-domain teammates when false. Defaults to true. | |
| from_assigned_gaps | No | Resolve the candidates from the owners of the period's missing-invoice gaps, server-side, instead of `person_ids`. The detected teammates are omitted, and `include_detected` is treated as false. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | ||
| roles | Yes | The assignable roles, `admin` or `member`, each with a one-line hint. | |
| success | Yes | ||
| targets | Yes | Where an invite can land: this workspace, plus any workspace group the caller belongs to. | |
| next_step | No | What to do with the card this result renders. Added by the dispatcher when the card asks for a click. | |
| candidates | Yes | ||
| me_person_id | Yes | The caller's own person id, so the card never offers to invite them. | |
| workspace_id | No | ||
| refusal_reason | No | Present only when the workspace refuses team invites. DEMO_WORKSPACE: the workspace holds sample data, so `candidates` and `targets` are empty on purpose. Tell the user to invite the team in their own workspace. | |
| 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. | |
| 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. | |
| 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. |