Well

Query records

well_query_records

Read-only

Read records from Well's context graph FOR YOUR OWN WORK. This draws nothing on the user's screen.

Use it for every read whose answer is yours rather than the reader's: a gate checking whether a window holds transactions, a totalCount an answer has to quote, a sync log's latest status, a field a later step needs, the rows behind a figure you are about to compute.

⚠️ TO SHOW THE USER A TABLE, CALL well_show_records INSTEAD. Same arguments, same rows, and it renders the root's own table. This tool cannot put one on screen, so a request to "show me my invoices" answered here leaves the user with prose where a table belongs.

⚠️ WORKFLOW:

Call well_get_schema(root) FIRST to discover the available fields.
Name in fields ONLY the extra values you need (5-15 typically). They are ADDED to the root's default projection in the payload you read.
Filter with whereClause so the read answers the question. A count under a filter beats reading rows and counting them yourself.

ROOTS (read-only — all 38): companies, people, connectors, workspaces, workspace_connectors, invoices, documents, notes, transactions, accounts, memberships, payment_means, invoice_payment_means, cards, checks, chat_conversations, ledger_accounts, journals, journal_entries, tax_rates, exchange_rates, invoice_transactions, media, emails, phones, web_links, locations, categories, invoice_items, account_balances, tasks, workspace_connector_sync_logs, blueprint_runs, billing_events, payslips, messages, calendars, calendar_events (The accounting graph — ledger_accounts, journals, journal_entries — and balances/rates are read-only projections owned by the sync/posting pipelines; query them for financial context, you cannot create/update them here. Sub-resources like emails/phones/locations are usually richer when read via their parent company/person.) ("messages" holds the messages Well sent outbound on a member's behalf — emails and WhatsApp; notifications to the member are not stored. A message is visible to its sender only, so a read returns the caller's own messages. Filter by sender_membership, recipient_person or recipient_address, message_category, channel, status.)

CATEGORY CATALOGS: "categories" holds two independent taxonomies, separated by category_type. Always filter on it — an unfiltered read mixes them:

whereClause: { category_type: { _eq: "company" } } is the COMPANY-CATEGORY catalog: the industry labels a counterparty carries, and the ids well_update_company({ category_ids }) accepts. There is no curated allowlist — the labels are minted during enrichment — so read them here rather than inventing a taxonomy.
whereClause: { category_type: { _eq: "transaction" } } is the management/transaction taxonomy.

TRANSACTION FIELD NAMES (root "transactions"; a path opens with "transactions", e.g. ["transactions", "counterparty"]):

The name of the other side is counterparty: the company paid on an outflow, the one who paid on an inflow. When it is empty, provider_label holds the name the bank gives that side. Both are computed when the row is read: select them, but never filter, sort or total on them. To filter on a supplier, filter creditor_payment_means.company.name.
remittance.unstructured is the payment reference the bank carries: an invoice number, or a code of the bank such as fx_card. It is never the name of the other side: never give it as a name, and never quote a bank code to the user. When counterparty and provider_label are both empty, use it only to say in plain words what the movement is: fx_card on a Qonto account is a Qonto currency exchange fee ("frais de change Qonto").
The amount is instructed_amount.amount with instructed_amount.currency. Its sign gives the direction (negative for an outflow) only when amount_sign is "signed"; on any other row, give the amount as it is and never call it an outflow or an inflow. The date is executed_at. status says where the payment stands.
A list of transactions for the user reads executed_at, counterparty, provider_label, remittance.unstructured, instructed_amount.amount, instructed_amount.currency and status, newest first (orderBy executed_at, desc).

TRANSACTION CATEGORY FIELDS (root "transactions"): Well's category of a transaction is on the transaction row itself:

category_normalized: the category label. category_key: the stable key of that label.
category_status: the categorization state (values: "categorized", "uncategorized", "classifier_abstained", "classifier_failed", "pending", "legacy_unmapped"). "pending" means a categorization run is queued or in flight. Whether the transaction has a category is decided by category_normalized alone. When category_normalized is empty, tell the user the transaction is not categorized yet, in the language of your reply.
category_source: who wrote the category (values: "classifier", "user", "connector", "rule").
To find the transactions that have a category, read or filter these fields, for example whereClause { category_normalized: { _is_null: false } }. To find the transactions without one, use { category_normalized: { _is_null: true } }.
The transaction_categories relation holds only the labels that an accounting connector sent with the transaction. A bank-feed transaction usually has none, and Well never writes one. Never read or filter transaction_categories to say that a transaction has a category or has no category.

ACCOUNT FIELD NAMES (root "accounts"; a path opens with "accounts", e.g. ["accounts", "account_name"]):

The label of an account is account_name. The accounts root has no name column: never select or filter "name" on it. From the account_balances root, the label is account.account_name.
Never filter accounts on a bank name. bank_company stays empty until Well identifies the bank, and account_name is the label the provider sends (for example "Plaid Checking"), so such a filter returns no row for an account the workspace holds.
For the accounts or the balance at a named bank, call well_list_account_balances and keep the rows whose institution_name is that bank. Never say that the workspace has no account at a bank from a records read.

CONNECTED TOOLS: do NOT use this tool to show the user what they have connected — call well_list_connectors instead. It owns that job: connection status, and an install link for anything not connected yet. Query root "workspace_connectors" here only for genuine RECORD-level needs — reading sync timestamps, filtering connections, joining them with other roots. ("connectors" is the installable catalog; "workspace_connector_sync_logs" is per-sync history.)

Well already syncs the providers' data into the roots above — invoices, transactions, accounts, the accounting graph. ALWAYS read it from here. well_invoke_connector_tool and a provider's own tools are for an ACTION the user explicitly asked to take on that provider (e.g. "create this record in Attio"), never a way to fetch data Well already holds.

FILTERING (whereClause):

Uses Hasura-style operators on field names.
Safe operators (work on ALL field types): _eq, _neq, _in, _nin, _is_null
Numeric/date only: _gt, _gte, _lt, _lte
Text only: _like, _ilike
When unsure of a field's type, prefer _eq or _in (they always work).
Combine with _and, _or, _not
For relationship fields, use nested syntax: { "issuer": { "company_id": { "_eq": "<company_id>" } } }
NEVER select the workspace's OWN records by matching a company name. One legal entity appears under several labels — a registered name, a trade name, a bank-issued label — so a name filter silently drops rows and the total reads as complete. On the invoices root, pass partyScope instead: it resolves the workspace's own side on the server, so this query needs no id lookup and no extra call. Call well_get_own_company for the id only when a root has no partyScope and you must filter on issuer_pk / receiver_pk or the nested company_id yourself.
Match a counterparty by id too whenever you have one. Reach for _ilike on a name only to DISCOVER candidates to show the user, never to compute a figure you will report. Examples: { "status": { "_eq": "unpaid" } } { "grand_total": { "_gt": 1000 } } { "local_currency": { "_eq": "EUR" } } { "_and": [{ "status": { "_eq": "unpaid" } }, { "grand_total": { "_gte": 500 } }] } { "issuer": { "company_id": { "_eq": "<company_id from well_get_own_company>" } } }

SORTING (orderBy):

Sort by any field: { field: "grand_total", direction: "desc" }
Default sort is by primary key ascending.

⚠️ RULES:

fields is ADDITIVE — it widens the data you receive on top of the root's default projection
Omitting fields (default view) or naming a few extras both beat allFields
Field paths from schema: "invoices.issuer.name" → ["invoices", "issuer", "name"]
NEVER guess a field name. Common misses: a transaction has no amount column (read ["transactions", "instructed_amount", "amount"] and its "currency"), an account has no name (read ["accounts", "account_name"]). An unknown field fails the call and the error lists the valid fields of the root: retry once with one of them.
Default 50 records per request, max 500.
Reading whether ANYTHING matches is one call at limit: 1: read totalCount, not the rows.

EXAMPLE - does the window hold any transactions at all? well_query_records({ root: "transactions", limit: 1, whereClause: { "executed_at": { "_gte": "2026-06-01", "_lt": "2026-09-01" } } }) // totalCount answers it. One row comes back and you ignore it.

EXAMPLE - answer "how much are our customers still owing us?": well_query_records({ root: "invoices", partyScope: "sales", limit: 1, whereClause: { "payment_status": { "_in": ["unpaid", "partial"] } }, sum: ["balance_due"] }) // totals answers it: one balance_due sum per currency, over every unpaid // invoice issued by the workspace. Quote it; never add up the rows, which are a page. // partyScope picks the side: "sales" is owed TO the workspace, "purchase" is owed BY it.

When party_scope.side_unknown is true the workspace has no resolved own company, so no side filter was applied: the rows and totals cover every invoice on both sides, and the side is not known. Say the side is unknown, never that the figure is the requested side's.

ONE CALL IS THE ANSWER — do not walk the root: Every response carries totalCount (ALL matches, not just this page) and records_url (the full web-app table, with your filter and sort already applied). Hand the link to the user for anything past this page.

A non-null nextCursor is NOT a to-do. It means more rows exist, which totalCount already told you and the link already covers.
Never compute a total from the rows. They are a page, so a figure added up from them changes with limit, orderBy and cursor, and the same question gets two answers. Pass sum and quote totals: it covers every match. A count is totalCount.
Never paginate to "be thorough". Large roots will exhaust the output limit mid-walk, and the user ends up with nothing legible.
Paginate ONLY for per-row work over every match that no aggregate can express, and tell the user the cost before starting. Then: pass the returned nextCursor as cursor; nextCursor: null is the last page.

Returns { rows, totalCount, nextCursor, totals (when sum was passed), party_scope (when partyScope was passed), success }.

Input Schema

TableJSON Schema

Name	Required	Description
`sum`	No	Numeric fields to total over EVERY row the filter matches, not over this page. The result's `totals` gives one group per currency, each with its row `count` and one sum per field, so the figure is the same whatever `limit`, `orderBy` or `cursor` you pass. Quote these sums for any total you report; never add up the rows. Fields it takes, per root: `invoices`: `balance_due` (in `local_currency`), `grand_total` (in `local_currency`), `paid_amount` (in `local_currency`); any other field is refused. At most 3 fields. Example: ["balance_due"].
`root`	Yes	The entity type to query — any of the 38 read-only roots (companies, people, connectors, workspaces, workspace_connectors, invoices, documents, notes, transactions, accounts, memberships, payment_means, invoice_payment_means, cards, checks, chat_conversations, ledger_accounts, journals, journal_entries, tax_rates, exchange_rates, invoice_transactions, media, emails, phones, web_links, locations, categories, invoice_items, account_balances, tasks, workspace_connector_sync_logs, blueprint_runs, billing_events, payslips, messages, calendars, calendar_events). Call well_get_schema(root) first to discover fields.
`limit`	No	Max records to return (default 50, max 500)
`cursor`	No	Opaque cursor for the next page. Omit for the first page, then pass nextCursor from the previous response.
`fields`	No	EXTRA field paths to add to the root's display view, for values you need to reason about. Each path is an array whose first segment is the root's table name — use the paths well_get_schema(root) returns verbatim, which is the root name for every root except people (whose table is peoples); a path opening with any other segment is dropped. Additive only: they widen the payload you receive, and the root's own display projection (the columns the Well web app shows, and the ones a table drawn from this query carries) stays what it is no matter what you pass here. A scalar a composite renders comes back AS that composite — asking for grand_total gets you composite_total_amount_currency, with grand_total inside it — so read `columns` for what was actually materialized. Omit unless you need a value the display view does not carry.
`layout`	No	The layout `records_url` opens the table in: one of table, kanban, calendar, gallery, chart, list, graph. Any other value is ignored. Omitted, a saved view keeps its own layout. It changes the link, never the rows.
`viewId`	No	A saved view of this workspace, by its id. The read applies the view's filters and sort (and, on well_show_records, its columns), and `records_url` opens the table on that view. `root` must be the view's root. `whereClause` narrows the view's rows further; `orderBy` and `columns` replace the view's own.
`groupBy`	No	The field whose values make the columns of a kanban (or group a calendar) when the table opens through `records_url`. One path in the `fields` format, opening with the root's table name, for example ["invoices", "status"]; a path that is not a field of the root's own row is dropped. Omitted, a saved view keeps its own grouping. It changes the link, never the rows.
`orderBy`	No	Sort results by a field. Example: { field: "grand_total", direction: "desc" }
`allFields`	No	If true, automatically fetches all scalar fields from schema. No need to specify fields.
`partyScope`	No	Which side of an invoice the workspace itself occupies, resolved from its own company rather than a party name. `invoices` root only. "purchase" = the workspace owes it (payables); "sales" = the workspace is owed (receivables); "intra_self" = both parties are companies the workspace owns; "unattributed" = Well cannot place it on either side. The four partition every invoice, so report the "unattributed" count beside any payable total rather than dropping it — an unattributed invoice may still be owed. Prefer this over hand-writing an issuer/receiver filter.
`whereClause`	No	Hasura-style filter object. Operators: _eq, _neq, _gt, _gte, _lt, _lte, _like, _ilike, _in, _nin, _is_null. Example: { "status": { "_eq": "unpaid" } }
`workspace_id`	No	Target workspace. Omit to query every authorized workspace at once; each row comes back tagged with the workspace it belongs to.
`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.

Output Schema

TableJSON Schema

Name	Required	Description
`rows`	Yes	Query results
`error`	No
`layout`	No	The layout the records card draws and `records_url` opens: the asked one, else the saved view's. Null when neither names one.
`totals`	No	Present when `sum` was passed and the total read succeeded: the sums over every matching row, one group per currency. `truncated: true` means the group list hit its cap and is incomplete. `completeness` (invoices root only) says how far the workspace's own-side resolution lets you trust the total: the self-party set's size and the counts of the rows it could not prove a side for.
`columns`	No	The materialized columns in display order, with each composite substituted in place of the source fields it consumed. A row object's key order does not preserve this — the flattener appends reconstructed composites last — so a UI that wants the web app's column order must read it from here.
`success`	Yes
`group_by`	No	The field path a kanban or a calendar groups the rows by: the asked one, else the saved view's. Each row carries its value.
`returned`	Yes	Number of rows returned
`columnMeta`	No	Per-column field meaning, keyed by the same column paths as the rows. `context` = what the field means; `enrichment` = how the value is sourced (e.g. Bank sync, AI extraction). Only documented columns appear. Read this to interpret the returned values.
`nextCursor`	No	Cursor for the next page. null means last page.
`totalCount`	Yes	Total matching records
`party_scope`	No	Present only when `partyScope` was passed: what the scope resolved to on this read. `side_unknown: true` means the workspace resolved no own company, so NO side filter was applied (`applied: false`) and the rows and totals cover invoices on BOTH sides — say the side is unknown, never that the figure is the requested side's.
`records_url`	No	Login-gated deep link to the FULL web-app records table for this root (real DataTable: composites, inline editing, resize/pin), carrying this call's `whereClause` and `orderBy` so it opens on the same rows. Hand it to the user for everything past this page — it is the answer to 'show me all of them', not pagination. Null when no workspace is in context or no web page serves the root.
`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.
`totals_unavailable`	No	Present instead of `totals` when `sum` was passed but no total could be measured (`timeout`, `error`, or `count_mismatch` when the total did not cover the same rows as `totalCount`). The rows are still a page: never add them up to stand in for the total. Say the total is unavailable.
`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.

Changed5 schema fields changedOct 14, 2026

addedInput schema / properties / groupBy

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "minItems": 2,
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "The field whose values make the columns of a kanban (or group a calendar) when the table opens through `records_url`. One path in the `fields` format, opening with the root's table name, for example [\"invoices\", \"status\"]; a path that is not a field of the root's own row is dropped. Omitted, a saved view keeps its own grouping. It changes the link, never the rows."
+}

addedInput schema / properties / layout

Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "table",
+        "kanban",
+        "calendar",
+        "gallery",
+        "chart",
+        "list",
+        "graph"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "The layout `records_url` opens the table in: one of table, kanban, calendar, gallery, chart, list, graph. Any other value is ignored. Omitted, a saved view keeps its own layout. It changes the link, never the rows."
+}

addedInput schema / properties / viewId

Added value: +{
+  "description": "A saved view of this workspace, by its id. The read applies the view's filters and sort (and, on well_show_records, its columns), and `records_url` opens the table on that view. `root` must be the view's root. `whereClause` narrows the view's rows further; `orderBy` and `columns` replace the view's own.",
+  "format": "uuid",
+  "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+  "type": "string"
+}

addedOutput schema / properties / group_by

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "The field path a kanban or a calendar groups the rows by: the asked one, else the saved view's. Each row carries its value."
+}

addedOutput schema / properties / layout

Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "table",
+        "kanban",
+        "calendar",
+        "gallery",
+        "chart",
+        "list",
+        "graph"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "The layout the records card draws and `records_url` opens: the asked one, else the saved view's. Null when neither names one."
+}

Changed1 schema field changedOct 13, 2026

changedOutput schema / properties / totals / properties / completeness / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "description": "How far the workspace's own-side resolution lets a caller trust the figure: the self-party set's size and truncation, and the counts of the rows it could not prove a side for. `unattributed_count` is the certainty-unknown remainder; `estimated` counts the rows a weak claim still sides, unavailable when the set was truncated or the read failed. A null count is an unread cell, never a measured zero.",
-    "properties": {
-      "conflict_count": {
-        "anyOf": [
-          {
-            "type": "number"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "estimated": {
-        "anyOf": [
-          {
-            "additionalProperties": false,
-            "properties": {
-              "available": {
-                "const": true,
-                "type": "boolean"
-              },
-              "count": {
-                "type": "number"
-              },
-              "kinds": {
-                "items": {
-                  "enum": [
-                    "own_set_self_candidate",
-                    "asserted_own_side_unqualified",
-                    "bank_allocation"
-                  ],
-                  "type": "string"
-                },
-                "type": "array"
-              }
-            },
-            "required": [
-              "available",
-              "count",
-              "kinds"
-            ],
-            "type": "object"
-          },
-          {
-            "additionalProperties": false,
-            "properties": {
-              "available": {
-                "const": false,
-                "type": "boolean"
-              },
-              "reason": {
-                "enum": [
-                  "own_set_truncated",
-                  "read_failed"
-                ],
-                "type": "string"
-              }
-            },
-            "required": [
-              "available",
-              "reason"
-            ],
-            "type": "object"
-          }
-        ]
-      },
-      "intra_self_count": {
-        "anyOf": [
-          {
-            "type": "number"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "personal_mode": {
-        "type": "boolean"
-      },
-      "self_candidate_count": {
-        "type": "number"
-      },
-      "self_set_size": {
-        "type": "number"
-      },
-      "self_set_truncated": {
-        "type": "boolean"
-      },
-      "unattributed_count": {
-        "anyOf": [
-          {
-            "type": "number"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      }
-    },
-    "required": [
-      "self_set_size",
-      "self_set_truncated",
-      "self_candidate_count",
-      "personal_mode",
-      "unattributed_count",
-      "intra_self_count",
-      "conflict_count",
-      "estimated"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "description": "How far the workspace's own-side resolution lets a caller trust the figure: the self-party set's size and truncation, and the counts of the rows it could not prove a side for. `unattributed_count` is the certainty-unknown remainder; `estimated` counts the rows a weak claim still sides, unavailable when the set was truncated or the read failed. A null count is an unread cell, never a measured zero.",
+    "properties": {
+      "conflict_count": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "estimated": {
+        "anyOf": [
+          {
+            "additionalProperties": false,
+            "properties": {
+              "available": {
+                "const": true,
+                "type": "boolean"
+              },
+              "count": {
+                "type": "number"
+              },
+              "kinds": {
+                "items": {
+                  "enum": [
+                    "own_set_self_candidate",
+                    "asserted_own_side_unqualified",
+                    "bank_allocation"
+                  ],
+                  "type": "string"
+                },
+                "type": "array"
+              }
+            },
+            "required": [
+              "available",
+              "count",
+              "kinds"
+            ],
+            "type": "object"
+          },
+          {
+            "additionalProperties": false,
+            "properties": {
+              "available": {
+                "const": false,
+                "type": "boolean"
+              },
+              "reason": {
+                "enum": [
+                  "own_set_truncated",
+                  "read_failed"
+                ],
+                "type": "string"
+              }
+            },
+            "required": [
+              "available",
+              "reason"
+            ],
+            "type": "object"
+          }
+        ]
+      },
+      "fold_version": {
+        "maximum": 9007199254740991,
+        "minimum": -9007199254740991,
+        "type": "integer"
+      },
+      "intra_self_count": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "personal_mode": {
+        "type": "boolean"
+      },
+      "self_candidate_count": {
+        "type": "number"
+      },
+      "self_set_size": {
+        "type": "number"
+      },
+      "self_set_truncated": {
+        "type": "boolean"
+      },
+      "unattributed_count": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      }
+    },
+    "required": [
+      "fold_version",
+      "self_set_size",
+      "self_set_truncated",
+      "self_candidate_count",
+      "personal_mode",
+      "unattributed_count",
+      "intra_self_count",
+      "conflict_count",
+      "estimated"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

Changed4 schema fields changedOct 12, 2026

changedOutput schema / properties / newly_connected / description

Previous value: -"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. Start the reply with 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."New value: +"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."

addedOutput schema / properties / party_scope

Added value: +{
+  "additionalProperties": false,
+  "description": "Present only when `partyScope` was passed: what the scope resolved to on this read. `side_unknown: true` means the workspace resolved no own company, so NO side filter was applied (`applied: false`) and the rows and totals cover invoices on BOTH sides — say the side is unknown, never that the figure is the requested side's.",
+  "properties": {
+    "applied": {
+      "type": "boolean"
+    },
+    "requested": {
+      "enum": [
+        "purchase",
+        "sales",
+        "intra_self",
+        "unattributed"
+      ],
+      "type": "string"
+    },
+    "side_unknown": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "requested",
+    "applied",
+    "side_unknown"
+  ],
+  "type": "object"
+}

changedOutput schema / properties / totals / description

Previous value: -"Present when `sum` was passed and the total read succeeded: the sums over every matching row, one group per currency. `truncated: true` means the group list hit its cap and is incomplete."New value: +"Present when `sum` was passed and the total read succeeded: the sums over every matching row, one group per currency. `truncated: true` means the group list hit its cap and is incomplete. `completeness` (invoices root only) says how far the workspace's own-side resolution lets you trust the total: the self-party set's size and the counts of the rows it could not prove a side for."

addedOutput schema / properties / totals / properties / completeness

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "description": "How far the workspace's own-side resolution lets a caller trust the figure: the self-party set's size and truncation, and the counts of the rows it could not prove a side for. `unattributed_count` is the certainty-unknown remainder; `estimated` counts the rows a weak claim still sides, unavailable when the set was truncated or the read failed. A null count is an unread cell, never a measured zero.",
+      "properties": {
+        "conflict_count": {
+          "anyOf": [
+            {
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "estimated": {
+          "anyOf": [
+            {
+              "additionalProperties": false,
+              "properties": {
+                "available": {
+                  "const": true,
+                  "type": "boolean"
+                },
+                "count": {
+                  "type": "number"
+                },
+                "kinds": {
+                  "items": {
+                    "enum": [
+                      "own_set_self_candidate",
+                      "asserted_own_side_unqualified",
+                      "bank_allocation"
+                    ],
+                    "type": "string"
+                  },
+                  "type": "array"
+                }
+              },
+              "required": [
+                "available",
+                "count",
+                "kinds"
+              ],
+              "type": "object"
+            },
+            {
+              "additionalProperties": false,
+              "properties": {
+                "available": {
+                  "const": false,
+                  "type": "boolean"
+                },
+                "reason": {
+                  "enum": [
+                    "own_set_truncated",
+                    "read_failed"
+                  ],
+                  "type": "string"
+                }
+              },
+              "required": [
+                "available",
+                "reason"
+              ],
+              "type": "object"
+            }
+          ]
+        },
+        "intra_self_count": {
+          "anyOf": [
+            {
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "personal_mode": {
+          "type": "boolean"
+        },
+        "self_candidate_count": {
+          "type": "number"
+        },
+        "self_set_size": {
+          "type": "number"
+        },
+        "self_set_truncated": {
+          "type": "boolean"
+        },
+        "unattributed_count": {
+          "anyOf": [
+            {
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "required": [
+        "self_set_size",
+        "self_set_truncated",
+        "self_candidate_count",
+        "personal_mode",
+        "unattributed_count",
+        "intra_self_count",
+        "conflict_count",
+        "estimated"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

Changed1 schema field changedOct 8, 2026

addedInput schema / properties / workspace_scope

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

Changed2 schema fields changedOct 6, 2026

changedInput schema / properties / root / description

Previous value: -"The entity type to query — any of the 35 read-only roots (companies, people, connectors, workspaces, workspace_connectors, invoices, documents, notes, transactions, accounts, memberships, payment_means, invoice_payment_means, cards, checks, chat_conversations, ledger_accounts, journals, journal_entries, tax_rates, exchange_rates, invoice_transactions, media, emails, phones, web_links, locations, categories, invoice_items, account_balances, tasks, workspace_connector_sync_logs, blueprint_runs, billing_events, payslips). Call well_get_schema(root) first to discover fields."New value: +"The entity type to query — any of the 38 read-only roots (companies, people, connectors, workspaces, workspace_connectors, invoices, documents, notes, transactions, accounts, memberships, payment_means, invoice_payment_means, cards, checks, chat_conversations, ledger_accounts, journals, journal_entries, tax_rates, exchange_rates, invoice_transactions, media, emails, phones, web_links, locations, categories, invoice_items, account_balances, tasks, workspace_connector_sync_logs, blueprint_runs, billing_events, payslips, messages, calendars, calendar_events). Call well_get_schema(root) first to discover fields."

addedOutput schema / properties / newly_connected

Added value: +{
+  "description": "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. Start the reply with 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.",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "name": {
+        "type": "string"
+      },
+      "service_id": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "name",
+      "service_id"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

Changed4 schema fields changedOct 6, 2026

changedInput schema / properties / root / description

Previous value: -"The entity type to query — any of the 33 read-only roots (companies, people, connectors, invoices, documents, transactions, accounts, payment_means, workspace_connectors, memberships, cards, checks, ledger_accounts, journals, journal_entries, tax_rates, exchange_rates, invoice_transactions, categories, account_balances, tasks, workspaces, invoice_payment_means, chat_conversations, blueprint_runs, workspace_connector_sync_logs, media, emails, phones, web_links, locations, invoice_items, billing_events). Call well_get_schema(root) first to discover fields."New value: +"The entity type to query — any of the 35 read-only roots (companies, people, connectors, workspaces, workspace_connectors, invoices, documents, notes, transactions, accounts, memberships, payment_means, invoice_payment_means, cards, checks, chat_conversations, ledger_accounts, journals, journal_entries, tax_rates, exchange_rates, invoice_transactions, media, emails, phones, web_links, locations, categories, invoice_items, account_balances, tasks, workspace_connector_sync_logs, blueprint_runs, billing_events, payslips). Call well_get_schema(root) first to discover fields."

addedInput schema / properties / sum

Added value: +{
+  "description": "Numeric fields to total over EVERY row the filter matches, not over this page. The result's `totals` gives one group per currency, each with its row `count` and one sum per field, so the figure is the same whatever `limit`, `orderBy` or `cursor` you pass. Quote these sums for any total you report; never add up the rows. Fields it takes, per root: `invoices`: `balance_due` (in `local_currency`), `grand_total` (in `local_currency`), `paid_amount` (in `local_currency`); any other field is refused. At most 3 fields. Example: [\"balance_due\"].",
+  "items": {
+    "minLength": 1,
+    "type": "string"
+  },
+  "maxItems": 3,
+  "minItems": 1,
+  "type": "array"
+}

addedOutput schema / properties / totals

Added value: +{
+  "additionalProperties": false,
+  "description": "Present when `sum` was passed and the total read succeeded: the sums over every matching row, one group per currency. `truncated: true` means the group list hit its cap and is incomplete.",
+  "properties": {
+    "grouped_by": {
+      "type": "string"
+    },
+    "groups": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "count": {
+            "anyOf": [
+              {
+                "type": "number"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "currency": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "sums": {
+            "additionalProperties": {
+              "anyOf": [
+                {
+                  "type": "number"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "propertyNames": {
+              "type": "string"
+            },
+            "type": "object"
+          }
+        },
+        "required": [
+          "currency",
+          "count",
+          "sums"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "truncated": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "grouped_by",
+    "groups",
+    "truncated"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / totals_unavailable

Added value: +{
+  "additionalProperties": false,
+  "description": "Present instead of `totals` when `sum` was passed but no total could be measured (`timeout`, `error`, or `count_mismatch` when the total did not cover the same rows as `totalCount`). The rows are still a page: never add them up to stand in for the total. Say the total is unavailable.",
+  "properties": {
+    "reason": {
+      "enum": [
+        "timeout",
+        "error",
+        "count_mismatch"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "reason"
+  ],
+  "type": "object"
+}

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 11, 2026

changedInput schema / properties / fields / description

Previous value: -"EXTRA field paths to add to the root's display view, for values you need to reason about. Each path is an array whose first segment is the root's table name — use the paths well_get_schema(root) returns verbatim, which is the root name for every root except people (whose table is peoples); a path opening with any other segment is dropped. Additive only: they widen the payload you receive, and the columns the user sees stay the root's display view (the ones the Well web app shows) no matter what you pass here. A scalar a composite renders comes back AS that composite — asking for grand_total gets you composite_total_amount_currency, with grand_total inside it — so read `columns` for what was actually materialized. Omit unless you need a value the display view does not carry."New value: +"EXTRA field paths to add to the root's display view, for values you need to reason about. Each path is an array whose first segment is the root's table name — use the paths well_get_schema(root) returns verbatim, which is the root name for every root except people (whose table is peoples); a path opening with any other segment is dropped. Additive only: they widen the payload you receive, and the root's own display projection (the columns the Well web app shows, and the ones a table drawn from this query carries) stays what it is no matter what you pass here. A scalar a composite renders comes back AS that composite — asking for grand_total gets you composite_total_amount_currency, with grand_total inside it — so read `columns` for what was actually materialized. Omit unless you need a value the display view does not carry."

Changed1 schema field changedAug 31, 2026

changedInput schema / properties / workspace_id / description

Previous value: -"Target workspace. Omit to use the only authorized workspace, or (for read tools) to query all authorized workspaces grouped by workspace. Required for write tools when the token authorizes more than one workspace."New value: +"Target workspace. Omit to query every authorized workspace at once; each row comes back tagged with the workspace it belongs to."

Changed1 schema field changedAug 20, 2026

addedInput schema / properties / partyScope

Added value: +{
+  "description": "Which side of an invoice the workspace itself occupies, resolved from its own company rather than a party name. `invoices` root only. \"purchase\" = the workspace owes it (payables); \"sales\" = the workspace is owed (receivables); \"intra_self\" = both parties are companies the workspace owns; \"unattributed\" = Well cannot place it on either side. The four partition every invoice, so report the \"unattributed\" count beside any payable total rather than dropping it — an unattributed invoice may still be owed. Prefer this over hand-writing an issuer/receiver filter.",
+  "enum": [
+    "purchase",
+    "sales",
+    "intra_self",
+    "unattributed"
+  ],
+  "type": "string"
+}

Changed1 schema field changedAug 6, 2026

changedOutput schema / properties / records_url / description

Previous value: -"Login-gated deep link to the FULL web-app records table for this root (real DataTable: composites, inline editing, resize/pin). Hand to the user to open the records view in one click. Null when no workspace is in context."New value: +"Login-gated deep link to the FULL web-app records table for this root (real DataTable: composites, inline editing, resize/pin), carrying this call's `whereClause` and `orderBy` so it opens on the same rows. Hand it to the user for everything past this page — it is the answer to 'show me all of them', not pagination. Null when no workspace is in context or no web page serves the root."

Changed2 schema fields changedAug 4, 2026

changedInput schema / properties / fields / description

Previous value: -"Array of field paths. Each path is an array starting with root name. Omit to get the root's default view (the columns the Well web app shows) — the right choice when displaying records to the user."New value: +"EXTRA field paths to add to the root's display view, for values you need to reason about. Each path is an array whose first segment is the root's table name — use the paths well_get_schema(root) returns verbatim, which is the root name for every root except people (whose table is peoples); a path opening with any other segment is dropped. Additive only: they widen the payload you receive, and the columns the user sees stay the root's display view (the ones the Well web app shows) no matter what you pass here. A scalar a composite renders comes back AS that composite — asking for grand_total gets you composite_total_amount_currency, with grand_total inside it — so read `columns` for what was actually materialized. Omit unless you need a value the display view does not carry."

changedInput schema / properties / root / description

Previous value: -"The entity type to query — any of the 32 read-only roots (companies, people, connectors, invoices, documents, transactions, accounts, payment_means, workspace_connectors, memberships, cards, checks, ledger_accounts, journals, journal_entries, tax_rates, exchange_rates, invoice_transactions, categories, account_balances, tasks, workspaces, invoice_payment_means, chat_conversations, blueprint_runs, workspace_connector_sync_logs, media, emails, phones, web_links, locations, invoice_items). Call well_get_schema(root) first to discover fields."New value: +"The entity type to query — any of the 33 read-only roots (companies, people, connectors, invoices, documents, transactions, accounts, payment_means, workspace_connectors, memberships, cards, checks, ledger_accounts, journals, journal_entries, tax_rates, exchange_rates, invoice_transactions, categories, account_balances, tasks, workspaces, invoice_payment_means, chat_conversations, blueprint_runs, workspace_connector_sync_logs, media, emails, phones, web_links, locations, invoice_items, billing_events). Call well_get_schema(root) first to discover fields."

Changed2 schema fields changedJul 31, 2026

changedInput schema / properties / fields / description

Previous value: -"Array of field paths. Each path is an array starting with root name. Optional if allFields is true."New value: +"Array of field paths. Each path is an array starting with root name. Omit to get the root's default view (the columns the Well web app shows) — the right choice when displaying records to the user."

addedOutput schema / properties / columns

Added value: +{
+  "description": "The materialized columns in display order, with each composite substituted in place of the source fields it consumed. A row object's key order does not preserve this — the flattener appends reconstructed composites last — so a UI that wants the web app's column order must read it from here.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

First observedJul 27, 2026

TDQS

Score is being calculated.

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?