Well

Create a new person (contact) in the current workspace. Use this tool when the user asks to add, create, or register a new contact, employee, or person. REQUIRED: first_name OPTIONAL: last_name, job_title After creation, enrichment runs asynchronously in the background. Returns { success: true, person_id, full_name } on success, or { success: false, error } on failure.

Delete a company from the current workspace (soft delete). Use this tool when the user asks to delete, remove, or archive a company. REQUIRED: company_id This soft-deletes the company and its company_person relationships. Linked people records themselves are NOT deleted. Invoices and documents referencing the company are preserved. Returns { success: true, company_id } on success, or { success: false, error } on failure.

Delete an invoice from Well (soft delete). REQUIRED: invoice_id Soft-deletes the invoice. Linked line items and payment_means rows are NOT cascade-deleted — they remain in the database, orphaned. The delete is reversible only at the database level.

Delete a person (contact) from the current workspace (soft delete). Use this tool when the user asks to delete, remove, or archive a contact. REQUIRED: person_id This soft-deletes the person and its company_person relationships. Linked companies themselves are NOT deleted. The authenticated user cannot delete their own person record. Returns { success: true, person_id } on success, or { success: false, error } on failure.

Read ONE entity with its sub-resources nested in a single call. Convenience over well_get_schema + well_query_records: resolves the field paths for you and returns the single record with its related data expanded. depth (relation-nesting BOUNDARY, 1-3, default 1): 1 = the entity + its direct sub-resources (emails, phones, locations, …) 2 = + the sub-resources' related scalars 3 = the full level-3 graph (LARGER payload — use when you need the whole picture) Stops at depth 3. Aggregates are excluded. Each child collection is capped at 50 rows; for a full list or to page a large child collection, use well_query_records on that child root instead.

Discover available data types and fields. USAGE: - well_get_schema() → List ALL available roots, including the accounting graph (ledger_accounts, journals, journal_entries) plus account_balances, tax_rates, exchange_rates — query these for real financial statements (compte de résultat / balance sheet) instead of reconstructing them from raw invoices - well_get_schema({ root: "invoices" }) → List all available fields for invoices WORKFLOW: 1. Call well_get_schema(root) to see available fields 2. Pick the fields you need for your task (typically 5-15) 3. Call well_query_records with those specific fields Returns fields with path, type, and (when documented) semantic context: - { path: "invoices.grand_total", type: "numeric", context: "Total invoice amount incl. tax in the document currency...", enrichment: "AI extraction" } → use _eq, _gt, _lt, etc. - { path: "invoices.local_currency", type: "enum" } → use ONLY _eq, _neq, _in, _nin, _is_null - { path: "invoices.issuer.name", type: "text" } → use _eq, _like, _ilike, etc. - "context" (when present) explains what the field MEANS in the domain and how it's used — read it to pick the right field and write correct filters. - "enrichment" (when present) is the value's provenance (e.g. "Bank sync", "AI extraction", "System generated", "Derived", "Manual"). Use the type to choose the right whereClause operators in well_query_records. To use in well_query_records, convert path to array: "invoices.issuer.name" → ["invoices", "issuer", "name"]

Run one tool on a connected provider's own MCP server (e.g. create a record in Attio), on behalf of this workspace's connection. WORKFLOW: 1. well_query_records({ root: "workspace_connectors", fields: [["workspace_connectors","workspace_connector_id"], ["workspace_connectors","connector","name"], ["workspace_connectors","status"], ["workspace_connectors","installed_capabilities"]] }) → pick the ENABLED provider, read its workspace_connector_id and installed_capabilities.available_tools. 2. well_invoke_connector_tool({ workspace_connector_id, tool: "<one of available_tools>", args: { ... } }). Only works on connectors that expose an MCP server (e.g. Attio, Notion, Linear) and whose connection is enabled. Returns the provider's tool result, or { success: false, error } if the tool failed / is not granted.

Discover the actions a connected provider exposes (e.g. "what can I do with Attio?"). WORKFLOW: 1. well_query_records({ root: "workspace_connectors", fields: [["workspace_connectors","workspace_connector_id"], ["workspace_connectors","connector","name"], ["workspace_connectors","status"]] }) → pick the ENABLED provider and its workspace_connector_id. 2. well_list_connector_tools({ workspace_connector_id }) → the actions that provider offers (name + description + input schema). 3. well_invoke_connector_tool({ workspace_connector_id, tool, args }) → run one, shaping args from the input schema returned here. Use this whenever you don't already know a connector's tool names — never guess them. Every response also carries reconnect_url: a deep link to the connector's setup page in the web app. When success is false or status is "need_reconnect" (the provider's token is stale/revoked, so no tools come back), give the user reconnect_url so they can re-authenticate the connector. Surface it as a clickable link; never invent connector URLs.

List the connectors a workspace can install, each with a one-click install deep link. Use this to answer "what can I connect to Well?" or "how do I connect <provider>?". Each entry has: - service_id: the connector's stable catalog id (e.g. "stripe"), used in the install link. - name, category_id, direction: what the connector is. - status: "available" connectors are connectable now; "coming_soon"/"unavailable"/"maintenance" are not. - is_matched / is_selected: whether this workspace's detected tools matched this connector / already picked it. - install_url: a login-gated deep link to install (or reconnect) this connector — present only for "available" connectors. Hand this to the user to connect in one click. The default view returns the curated, matched-first connectors; pass q to name-search the full catalog (e.g. a specific bank). This is the catalog of POTENTIAL connections — for what is ALREADY connected, query the workspace_connectors records, then well_list_connector_tools for a live connection's actions.

List the workspaces this connection is authorized to access. Use this FIRST when a single token may cover more than one workspace. Each entry has: - workspace_id: pass this as the workspace_id argument on other tools to target one workspace. - workspace_name: human-readable name (null if it can't be resolved). - is_primary: true for the token's default workspace (used when you omit workspace_id on a write). When the token authorizes a single workspace you can omit workspace_id everywhere; when it authorizes several, read tools fan out across all of them unless you pass a workspace_id, and write tools require one.

Query records from Well's database. ⚠️ WORKFLOW: 1. Call well_get_schema(root) FIRST to discover available fields 2. Select ONLY the fields you need (5-15 typically) 3. Call well_query_records with those specific fields ROOTS (read-only — all 32): 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 (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.) INSTALLED CONNECTORS: to see which tools/providers the workspace has connected and their connection status, query root "workspace_connectors" (fields: ["workspace_connectors","status"], ["workspace_connectors","connector","name"], ["workspace_connectors","connector","slug"], ["workspace_connectors","installed_capabilities"]). "connectors" is the installable catalog; "workspace_connector_sync_logs" is per-sync history. The installed_capabilities.available_tools list names the actions a connected provider exposes (run one with well_invoke_connector_tool). EXAMPLE - Get all invoices for dashboard: well_query_records({ root: "invoices", fields: [ ["invoices", "invoice_number"], ["invoices", "grand_total"], ["invoices", "issue_date"], ["invoices", "issuer", "name"], ["invoices", "receiver", "name"] ], limit: 50 }) ⚠️ RULES: - ALWAYS select specific fields (not allFields) for best performance - Field paths from schema: "invoices.issuer.name" → ["invoices", "issuer", "name"] - Default 50 records per request, max 500. Use cursor pagination for more. PAGINATION (cursor-based): - First call: omit cursor. Response includes nextCursor. - Next page: pass the returned nextCursor as cursor. - Last page: nextCursor is null. Example: Page 1: well_query_records({ root: "invoices", fields: [...], limit: 50 }) → { rows: [...], nextCursor: "eyJpZCI6MTAwfQ==" } Page 2: well_query_records({ root: "invoices", fields: [...], limit: 50, cursor: "eyJpZCI6MTAwfQ==" }) → { rows: [...], nextCursor: null } // last page 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": { "name": { "_ilike": "%acme%" } } } Examples: { "status": { "_eq": "unpaid" } } { "grand_total": { "_gt": 1000 } } { "local_currency": { "_eq": "EUR" } } { "_and": [{ "status": { "_eq": "unpaid" } }, { "grand_total": { "_gte": 500 } }] } { "issuer": { "name": { "_ilike": "%acme%" } } } SORTING (orderBy): - Sort by any field: { field: "grand_total", direction: "desc" } - Default sort is by primary key ascending. Returns { rows, totalCount, nextCursor, success }.

Remove a contact channel from a company or person. Wraps the resource-scoped DELETE endpoints (DELETE /v1/{companies,people}/:id/{emails,phones,web-links,locations}/:channelId). Pass channel_id = the UUID of the specific channel row to remove (NOT the parent). Find it by reading the parent with well_query_records and selecting the channel's id field.

Update an existing company in the current workspace. Use this tool when the user asks to change, fix, rename, or edit a company's fields. REQUIRED: company_id OPTIONAL (only include fields the user wants changed): name, description, domain, registered_name, trade_name, tax_id_value, tax_id_type, registry_country (ISO 3166-1 alpha-2, e.g. "FR"), business_type, registered_value, registry_name, locale (ISO 639-1 two-letter language code, e.g. "en", "fr" — not "en_US"). NOT CHANGEABLE via this tool: emails, phones, locations, linked people, media. Those require dedicated tools (not yet available). Returns { success: true, company_id, name } on success, or { success: false, error } on failure.

Update an existing invoice in Well. Call well_get_schema("invoices") to discover all available fields. REQUIRED: invoice_id OPTIONAL (only pass fields you want changed): - reference_number, issue_date (ISO date), due_date (ISO date) - status (draft | issued | paid | canceled) - terms, description - grand_total, items_total, tax_total (numbers) - local_currency (ISO 4217 three-letter code, e.g. "EUR", "USD") - document_type_code (UN/CEFACT 1001 code, e.g. "380") - billing_context (e.g. subscription, one_time, project, ...) - issuer_company_id / receiver_company_id (uuid to set, null to clear, omit to leave unchanged) Cannot change line items, payment_means, or document attachment via this tool.

Update an existing person (contact) in the current workspace. Use this tool when the user asks to change, fix, rename, or edit a person's fields. REQUIRED: person_id OPTIONAL (only include fields the user wants changed): first_name, last_name, job_title. NOT CHANGEABLE via this tool: emails, phones, locations, linked companies, media. Those require dedicated tools (not yet available). Returns { success: true, person_id, full_name } on success, or { success: false, error } on failure.