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:
1. Call well_get_schema(root) FIRST to discover the available fields.
2. 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.
3. 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 73): 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, projects, shipments, activities, company_relations, connector_filters, employment_contracts, field_definitions, payslip_line_rubrics, subscriptions, supplier_payment_terms, workspace_category_overrides, workspace_groups, products, inventories, inventory_movements, daily_metrics, allocations, project_changes, shipment_events, statutory_values, adoption_scopes, browser_skills, canvas_views, connector_requests, document_layouts, expense_notes, field_rules, flow_runs, memory_units, share_links, skills, transaction_category_rules, workspace_posting_mappings, workspace_schedules, workspace_views
(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 Well's whereClause operators (underscore-prefixed, e.g. _eq, _ilike, _and) 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
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 newest first on `created_at`; transactions sort on `executed_at`, companies and
people by name.
⚠️ 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 }.
