well_show_records

io.github.WellApp-ai/well-mcp · Verify this server

Put a table of records IN FRONT OF THE USER. Use it when the user asked to SEE rows — "show me my invoices", "list my companies", "which suppliers have no category" — and when the answer you owe them IS the table. The table is ALWAYS the root's display view in the Well web app's column order, trimmed on the widest roots to what fits a chat-width table. You never choose columns for presentation: omit `fields` and the right ones render. ⚠️ FOR A READ THAT IS YOURS RATHER THAN THEIRS, CALL `well_query_records` INSTEAD. Same arguments, same rows, no table. Every gate, count, freshness check and intermediate read belongs there — this tool renders on every call, so using it for an internal check drops a table into a conversation about something else. ⚠️ DO NOT NARRATE THE TABLE. The card already shows these rows; restating them as markdown gives the user the table and a duplicate list under it. Two things the table cannot say for itself belong in your text: `totalCount` when it exceeds what is displayed ("showing the 50 most recently updated of 214"), and the `records_url` link for everything the card truncates. ⚠️ ONE CARD PER TURN. A turn draws at most one table, and never a table beside a card that is waiting for a click. ROOTS (read-only — all 33): 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 (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.) 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. 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: - Omit `fields` to show the user a table — that is what renders the root's own columns - `fields` is ADDITIVE and for values YOU need to reason about: it widens the payload you read and never reorders or trims the columns the user sees - Field paths from schema: "invoices.issuer.name" → ["invoices", "issuer", "name"] - Default 50 records per request, max 500. EXAMPLE - show the user their invoices (no `fields`, ever): well_show_records({ root: "invoices", limit: 50 }) 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). So a request to see a record type is ONE call: the user gets a table of the first page, the count tells them how many there are, and the link takes them to the rest. "Show me all my invoices" is answered by one call plus the link — NOT by fetching 483 rows into this conversation. - 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 paginate to compute a total, count, average or breakdown: aggregate over the filtered set instead. Summing a paginated sample produces a wrong number. - 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, success }.