Querying Well Data

---
name: querying-well-data
description: How to query a Well workspace correctly — discover the schema first, then query the right root. Use whenever the user asks about their invoices, companies, contacts, bank transactions, accounts, or accounting ledger in Well, or before writing any well_query_records call.
---

# Querying Well data

Well exposes a workspace's financial graph through three MCP tools:

- `well_get_schema()` — list every available **root** (entity type).
- `well_get_schema({ root })` — list the fields available on one root, with types and semantic context.
- `well_query_records({ root, fields, whereClause?, orderBy?, limit? })` — read rows.
- `well_get_entity({ root, id })` — fetch one record by id.

## The one rule: discover before you query

**Always call `well_get_schema(root)` first**, pick the fields you need from what it returns, then call `well_query_records`. Field paths are arrays: `"invoices.issuer.name"` → `["invoices", "issuer", "name"]`. Do not guess field names — they vary by root and are documented in the schema response (each field carries a `type` and often a `context` explaining what it means).

## The roots you can read

Calling `well_get_schema()` with no argument returns the full set. It includes far more than invoices and companies — in particular the **accounting graph**:

- **Commercial documents:** `invoices`, `invoice_items`, `invoice_transactions`
- **Parties:** `companies`, `people`, `payment_means`
- **Banking:** `accounts`, `transactions`, `account_balances`
- **Accounting graph (read-only, posted by Well's pipelines):** `ledger_accounts`, `journals`, `journal_entries`
- **Reference:** `tax_rates`, `exchange_rates`, `categories`, `connectors`
- **Workspace:** `memberships`, `tasks`, `workspace_connectors`

If you are about to answer a financial question by reconstructing it from raw invoices, **stop and check `well_get_schema()` first** — the posted ledger (`journal_entries`, `ledger_accounts`) is almost always the correct, more accurate source. See the `well:compte-de-resultat` and `well:balance-sheet` skills.

## Filtering

`whereClause` is a Hasura-style boolean expression. Use the operator the field's `type` allows (from the schema):

- `numeric` / `date` → `_eq`, `_gt`, `_lt`, `_gte`, `_lte`
- `enum` → `_eq`, `_neq`, `_in`, `_nin`, `_is_null`
- `text` → `_eq`, `_like`, `_ilike`
- relations → nest: `{ "issuer": { "name": { "_ilike": "%acme%" } } }`

## Gotchas

- Reads are scoped to the authenticated workspace automatically — you never pass a workspace id.
- Select the specific fields you need (5–15), not everything — it is faster and cheaper.
- Amounts on commercial documents are in the document currency; check the schema `context` for currency fields before summing across currencies (see `exchange_rates`).