Well

List member candidates

well_list_member_candidates

Read-only

List 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.

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. Set include_detected false 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.

⚠️ 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 other tool 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

TableJSON Schema

Name	Required	Description
`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.
`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

TableJSON Schema

Name	Required	Description
`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
`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.
`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.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedSep 22, 2026

addedInput schema / properties / conversation_id

Added value: +{
+  "description": "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.",
+  "type": "string"
+}

addedOutput schema / properties / conversation_id

Added value: +{
+  "description": "The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.",
+  "type": "string"
+}

addedOutput schema / properties / conversation_id_note

Added value: +{
+  "description": "Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.",
+  "type": "string"
+}

addedOutput schema / properties / conversation_id_source

Added value: +{
+  "description": "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened.",
+  "enum": [
+    "host_meta",
+    "argument",
+    "minted"
+  ],
+  "type": "string"
+}

Changed1 schema field changedSep 16, 2026

addedOutput schema / properties / next_step

Added value: +{
+  "description": "What to do with the card this result renders. Added by the dispatcher when the card asks for a click.",
+  "type": "string"
+}

Changed5 schema fields changedSep 10, 2026

addedInput schema / properties / calendar_month

Added value: +{
+  "description": "Calendar month, 1 = January … 12 = December. `from_assigned_gaps` only, paired with `calendar_year`.",
+  "maximum": 12,
+  "minimum": 1,
+  "type": "integer"
+}

addedInput schema / properties / calendar_year

Added value: +{
+  "description": "Calendar year, e.g. 2026. `from_assigned_gaps` only.",
+  "maximum": 2100,
+  "minimum": 2000,
+  "type": "integer"
+}

addedInput schema / properties / fiscal_period

Added value: +{
+  "description": "Fiscal period, 1-12. `from_assigned_gaps` only, paired with `fiscal_year`. The adjustment period (13) is refused.",
+  "maximum": 13,
+  "minimum": 1,
+  "type": "integer"
+}

addedInput schema / properties / fiscal_year

Added value: +{
+  "description": "Fiscal year (the calendar year the workspace's fiscal year STARTED in). `from_assigned_gaps` only.",
+  "maximum": 2100,
+  "minimum": 2000,
+  "type": "integer"
+}

addedInput schema / properties / from_assigned_gaps

Added value: +{
+  "description": "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.",
+  "type": "boolean"
+}

AddedSep 8, 2026

TDQS

A5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, and the description goes well beyond: it details the return structure (candidates, targets, roles, me_person_id), the three sourcing modes, state semantics, and the requirement to wait on the card and call well_wait_for_selection. It also clarifies that the read does not guess the workspace when multiple are authorized.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Long but efficient—every sentence carries operational guidance. Organized into clear paragraphs (purpose, returns, sourcing modes, card interaction, authorization) and front-loads the primary purpose. No redundant phrasing; each sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 9 parameters, an output schema, and a multi-step card interaction, the description covers everything: return fields, state/source semantics, sourcing modes, period rules, conversation_id handling, authorization, and the card footer's role. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Even though the schema covers all 9 parameters, the description adds critical interaction semantics: from_assigned_gaps overrides include_detected, period must be named one of two ways, conversation_id must be passed back, and the default behavior of include_detected. This is meaning beyond the schema's individual descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'List the teammates a workspace can invite' and ties it to the Well app's invite card. It also names the sibling it is not: 'Use it before well_invite_members', making it unmistakable which action this covers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use it (before well_invite_members, for 'who can I invite') and when not to (never call well_invite_members after a click). It also gives conditional guidance for workspace_id based on token authorization and explains the card wait step.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Well tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?