Well MCP — MCP Radar

well_add_contact_channel

Add contact channel

Add a contact channel to a company or person. Wraps the resource-scoped REST endpoints (POST /v1/{companies,people}/:id/{emails,phones,web-links,locations}). channel + the matching value field: - email → value.email - phone → value.e164_number (E.164; a leading "+" is added if missing) - web_link → value.url (+ optional value.platform, default "website") - location → value.city, value.country (+ optional address_line1/2, region, postal_code) value.label is optional (defaults to "work"). NOTE: adding a phone is supported on a PERSON but NOT on a company (no endpoint) — that combination returns a clear error. To READ existing channels, use well_query_records on the parent (companies/people) or the channel root.

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['parent', 'parent_id', 'channel', 'value'], 'properties': {'value': {'type': 'object', 'properties': {'url': {'type': 'string', 'maxLength': 255, 'description': 'web_link channel: the URL'}, 'city': {'type': 'string', 'maxLength': 255, 'description': 'location channel: city'}, 'email': {'type': 'string', 'maxLength': 320, 'description': 'email channel: the address'}, 'label': {'type': 'string', 'description': "optional label (default 'work')"}, 'region': {'type': 'string', 'maxLength': 255}, 'country': {'type': 'string', 'maxLength': 2, 'description': 'location channel: 2-letter country code'}, 'platform': {'type': 'string', 'description': "web_link channel: platform (default 'website')"}, 'e164_number': {'type': 'string', 'maxLength': 255, 'description': 'phone channel: number (E.164)'}, 'postal_code': {'type': 'string', 'maxLength': 255}, 'address_line1': {'type': 'string', 'maxLength': 255}, 'address_line2': {'type': 'string', 'maxLength': 255}}, 'description': 'Channel value — fill the field(s) for the chosen channel'}, 'parent': {'enum': ['company', 'person'], 'type': 'string', 'description': 'Parent record type: company or person'}, 'channel': {'enum': ['email', 'phone', 'web_link', 'location'], 'type': 'string', 'description': 'Channel to add: email | phone | web_link | location'}, 'parent_id': {'type': 'string', '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)$', 'description': 'UUID of the parent company or person'}, 'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.'}, 'conversation_id': {'type': 'string', '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.'}, 'idempotency_key': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'error': {'type': 'string'}, 'parent': {'type': 'string'}, 'channel': {'type': 'string'}, 'success': {'type': 'boolean'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_assign_account

Assign account

Attach a bank account to a company, and say whether the workspace owns it. Use this when an account carries no company, or when its ownership is still `unknown` — the two states a figure that walks account ownership cannot be computed over. REQUIRED: account_id, plus at least one of company_id or ownership. `ownership` is one of: - "workspace" — the business's own account - "counterparty" — someone else's, seen on an invoice or a payment - "unknown" — not yet classified **This changes figures, not just a label.** An account marked "workspace" puts its transactions inside the internal-transfer rule: a movement with both legs on owned accounts stops counting as money leaving the business. Marking a counterparty's account as the workspace's own therefore removes real spend from the burn, quietly and consistently, with no error anywhere. So do not guess it. An account's owner cannot be read off its name, its bank, or the company that appears most often beside it. Ask, or leave it `unknown` — "not yet classified" is a truthful state and a wrong classification is not. `company_id` must name a company in the SAME workspace as the account; a company from another workspace is refused rather than resolved. Pass `company_id: null` to detach. Returns { success: true, account_id, ownership, company_id } on success.

Destructive

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['account_id'], 'properties': {'ownership': {'enum': ['workspace', 'counterparty', 'unknown'], 'type': 'string', 'description': 'Whether the workspace owns the account: "workspace", "counterparty", or "unknown".'}, 'account_id': {'type': 'string', '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)$', 'description': 'The UUID of the account to assign (required)'}, 'company_id': {'anyOf': [{'type': 'string', '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': 'null'}], 'description': 'The company that owns the account, in the same workspace. `null` detaches it.'}, 'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.'}, 'conversation_id': {'type': 'string', '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.'}, 'idempotency_key': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'error': {'type': 'string'}, 'success': {'type': 'boolean'}, 'ownership': {'type': 'string'}, 'account_id': {'type': 'string'}, 'company_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'company_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_assign_missing_invoice_owners

Assign missing-invoice owners

Set the owner SET of the missing-invoice TRANSACTIONS you name — the only write for missing-invoice ownership. REQUIRED: transaction_ids — the settled lines still missing a supplier invoice, from well_list_missing_invoice_owners. owner_person_ids — the people who together owe those invoices; pass an EMPTY array to clear the owners. Ownership is per TRANSACTION and is a SET, not one owner and not a card rule. The write REPLACES the owner set on every named transaction: the people you send become its owners and anyone not sent is removed. Assigning several people to a (counterparty × month) gap creates ONE proof task per distinct person, and ONE supplier invoice resolves every owner's task for that gap — the fan-out is for accountability, not for N separate collections. Tell the user this plainly. Each person_id must already be a member of the workspace (get them with well_query_records on people). A person outside the workspace is refused (refusal_reason NOT_FOUND), not silently dropped. Closed periods are frozen: a transaction whose fiscal month already closed refuses the whole batch (refusal_reason CLOSE_OWNER_PERIOD_FROZEN) rather than rewriting a committed close. A transaction id the workspace does not own refuses the batch too (refusal_reason NOT_FOUND).

Destructive

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['transaction_ids', 'owner_person_ids'], 'properties': {'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.'}, 'conversation_id': {'type': 'string', '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.'}, 'idempotency_key': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.'}, 'transaction_ids': {'type': 'array', 'items': {'type': 'string', '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)$'}, 'minItems': 1, 'description': 'The missing-invoice transactions to assign, from well_list_missing_invoice_owners.'}, 'owner_person_ids': {'type': 'array', 'items': {'type': 'string', '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)$'}, 'description': "The workspace people who together own these transactions' missing invoices; an empty array clears the owners."}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'error': {'type': 'string'}, 'success': {'type': 'boolean'}, 'owner_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'How many people own each of those transactions after the write.'}, 'refusal_reason': {'type': 'string', 'description': 'The WellError code when the write is refused — CLOSE_OWNER_PERIOD_FROZEN for a closed month, NOT_FOUND for a person outside the workspace or a transaction the workspace does not own.'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'refusal_details': {'type': 'object', 'description': 'Structured facts a refusal code alone does not carry — for CLOSE_OWNER_PERIOD_FROZEN, the frozen `{ fiscalYear, fiscalPeriod }`. A NOT_FOUND names the offending id in `error` instead.', 'propertyNames': {'type': 'string'}, 'additionalProperties': {}}, 'transaction_ids': {'type': 'array', 'items': {'type': 'string'}, 'description': 'The distinct transactions whose owner set the write replaced.'}, 'owner_person_ids': {'type': 'array', 'items': {'type': 'string'}, 'description': 'The explicit owner set written to every named transaction; empty when the owners were cleared.'}, 'transaction_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'How many distinct transactions the write touched.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_claim_statement_draft

Claim a statement dropped on the website

Claim every bank statement the user dropped on Well's website in one visit, using the ONE claim token from their message or from the /import-statement command argument. The token covers every file in that drop: call this tool once per token, never per file. It works once and expires an hour after the drop. Returns one document_id per file; poll well_get_statement_import_result for each. A refused token (expired, already claimed, unknown) is final: tell the user plainly and ask them to attach the files here, never retry. Files listed under failed were claimed but did not ingest; ask for exactly those by hand.

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['claim_token'], 'properties': {'claim_token': {'type': 'string', 'pattern': '^[A-Za-z0-9_-]{43}$', 'description': "The drop's claim token, exactly as written: from the argument after /import-statement or from the user's message. Single-use, covers every statement in that drop, expires one hour after the drop."}, 'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.'}, 'conversation_id': {'type': 'string', '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.'}, 'idempotency_key': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success', 'documents', 'failed'], 'properties': {'error': {'type': 'string'}, 'failed': {'type': 'array', 'items': {'type': 'object', 'required': ['draft_id', 'ordinal', 'filename', 'error'], 'properties': {'error': {'type': 'string'}, 'ordinal': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'draft_id': {'type': 'string'}, 'filename': {'type': 'string'}}, 'additionalProperties': False}, 'default': [], 'description': 'Files that were claimed but did not ingest. Their bytes are gone; ask the user for exactly these by name.'}, 'drop_id': {'type': 'string', 'description': 'The drop this token belonged to. Safe to quote; the token is not.'}, 'success': {'type': 'boolean'}, 'documents': {'type': 'array', 'items': {'type': 'object', 'required': ['draft_id', 'ordinal', 'filename', 'document_id', 'content_sha256', 'byte_length', 'deduplicated'], 'properties': {'ordinal': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': "The file's 0-based index among the files Well accepted from the drop, in arrival order."}, 'draft_id': {'type': 'string'}, 'filename': {'type': 'string'}, 'byte_length': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'document_id': {'type': 'string', 'description': 'Poll well_get_statement_import_result with this id for the import outcome.'}, 'deduplicated': {'type': 'boolean', 'description': 'True when an identical document was already in the workspace, so nothing was imported twice.'}, 'content_sha256': {'type': 'string'}}, 'additionalProperties': False}, 'default': [], 'description': 'One entry per file that reached the import pipeline.'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_create_company

Create company

Create a new company in the current workspace. Use this tool when the user asks to create, add, or register a new company. REQUIRED: name OPTIONAL: description After creation, enrichment (logo, domain, industry, tax ID, description fill-in) runs asynchronously in the background. The new company is available immediately for follow-up actions, but enriched fields may take a few seconds to populate — re-query after a brief delay to see them. Returns { success: true, company_id, name } on success, or { success: false, error } on failure.

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['name'], 'properties': {'name': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Company name (required)'}, 'description': {'type': 'string', 'maxLength': 250, 'minLength': 1, 'description': 'Brief company description'}, 'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.'}, 'conversation_id': {'type': 'string', '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.'}, 'idempotency_key': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'name': {'type': 'string'}, 'error': {'type': 'string'}, 'success': {'type': 'boolean'}, 'company_id': {'type': 'string'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_create_company_candidate

Create a company candidate

Mint a company candidate from a registry hit, the step between finding the company and creating its workspace. This is the deliberate pick the confirm-your-company card makes. REQUIRED: registry_ref — the `id` of a well_search_company_registry hit. This tool hydrates that hit and mints the company as a primary (own-company) candidate. Then call well_create_company_workspace with the returned `candidate_id` to make it the company workspace. Only a workspace owner or admin may mint a candidate. A caller without that role is refused, not silently ignored. When the picked company already has a confirmed company workspace, the result carries `linked_to_existing_child: true` and its `workspace_id` — switch into it with well_switch_workspace instead of creating another. Confirm the exact company with the user before calling; never pick one from a name alone.

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['registry_ref'], 'properties': {'registry_ref': {'type': 'string', 'maxLength': 2000, 'minLength': 1, 'description': 'The registry ref an earlier well_search_company_registry hit carried as its `id`.'}, 'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.'}, 'conversation_id': {'type': 'string', '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.'}, 'idempotency_key': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success', 'linked_to_existing_child', 'workspace_id', 'candidate'], 'properties': {'error': {'type': 'string'}, 'success': {'type': 'boolean'}, 'candidate': {'anyOf': [{'type': 'object', 'required': ['candidate_id', 'company_id', 'registered_name', 'trade_name', 'role', 'state', 'confidence_score', 'confirmable', 'confirmable_reason'], 'properties': {'role': {'anyOf': [{'enum': ['primary', 'sibling'], 'type': 'string'}, {'type': 'null'}]}, 'state': {'enum': ['pending', 'confirmed', 'dismissed', 'snoozed'], 'type': 'string'}, 'company_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': 'Null on a fresh candidate; a company row is resolved only once the workspace is created.'}, 'trade_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'confirmable': {'type': 'boolean'}, 'candidate_id': {'type': 'string'}, 'registered_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'confidence_score': {'type': 'number'}, 'confirmable_reason': {'anyOf': [{'enum': ['not_open', 'not_surfaceable', 'not_primary', 'already_confirmed', 'not_grounded'], 'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}, {'type': 'null'}], 'description': 'The minted candidate, projected as well_get_own_company shows a candidate; null when linked to an existing child.'}, 'workspace_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': 'The existing company workspace when linked_to_existing_child is true; null otherwise.'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}, 'linked_to_existing_child': {'type': 'boolean', 'description': 'True when the picked company already has a confirmed company workspace; its id is in workspace_id.'}}, 'additionalProperties': False}

well_create_company_workspace

Create the company workspace

Create the company workspace from a candidate, the step that turns a picked company into a workspace the close runs in. This anchors the candidate's company as the new workspace's own company and links it to the membership it was created under. REQUIRED: candidate_id — from well_create_company_candidate. This mints the child workspace, projects its accounting settings from the country defaults, anchors its own company, and writes the lineage row, so well_switch_workspace can move into it in the same conversation. Idempotent: calling it again on the same candidate returns the same child, with already_anchored true. Only a workspace owner or admin may create the company workspace. A caller without that role is refused, not silently ignored. Confirm the company with the user before calling.

Idempotent

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['candidate_id'], 'properties': {'candidate_id': {'type': 'string', '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)$', 'description': 'The candidate id returned by well_create_company_candidate.'}, 'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.'}, 'conversation_id': {'type': 'string', '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.'}, 'idempotency_key': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "The company workspace's name, derived from the candidate."}, 'error': {'type': 'string'}, 'success': {'type': 'boolean'}, 'workspace_id': {'type': 'string', 'description': "The created (or existing) company workspace's id."}, 'own_company_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "The public id of the company anchored as the workspace's own."}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'already_anchored': {'type': 'boolean', 'description': 'True when this call did not mint a fresh workspace: the candidate had already minted its child (a converged replay) or resolved to a company already anchored on the caller. The same child is returned either way.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_create_invoice_document

Create invoice document

Render an existing invoice as a print-ready PDF and attach it as the invoice's source document. The letterhead carries the issuing company's own mark when Well has one on file, and otherwise sets the issuer's name as text. Never promise a logo. Use this tool when the user asks to generate, render, or attach a PDF for an invoice that already exists in the workspace. This does NOT email or send the invoice anywhere — it only creates and attaches the file. REQUIRED: invoice_id (the invoice must already exist) Refused if the invoice is already linked to a REAL ingested document (an upload, a connector import, or a provider-issued PDF) — that source of truth is never overwritten. Returns { success: true, invoice_id, document_id, reference_number, file } on success, or { success: false, error } on failure. `file` carries the rendered PDF's name and size plus the links to fetch it: `download_url` (saves the file), `signed_url` (opens it), and `app_url` (the document in Well). Hand the user `download_url` when they ask for the PDF itself. Both signed links stop working at `expires_at`; `app_url` does not.

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['invoice_id'], 'properties': {'invoice_id': {'type': 'string', '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)$'}, 'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.'}, 'conversation_id': {'type': 'string', '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.'}, 'idempotency_key': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'file': {'type': 'object', 'required': ['name', 'size_bytes', 'signed_url', 'download_url', 'app_url', 'expires_at'], 'properties': {'name': {'type': 'string'}, 'app_url': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'expires_at': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'signed_url': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'size_bytes': {'type': 'number'}, 'download_url': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}, 'error': {'type': 'string'}, 'success': {'type': 'boolean'}, 'invoice_id': {'type': 'string'}, 'document_id': {'type': 'string'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'reference_number': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_create_invoice_from_data

Create invoice from data

Create an invoice in Well from data you extracted by reading an invoice (your own OCR) — you send the structured fields, not the file. Well persists the invoice + its line items + payment means using the same pipeline as uploaded documents. Fill every field you can read from the document: - issuer / receiver: { name (required), company_id?, domain?, tax_id? } - reference_number, issue_date (YYYY-MM-DD), due_date? (YYYY-MM-DD), currency (ISO 4217) - totals?: { items_total?, tax_total?, grand_total } - line_items[]: { name, quantity?, unit_price, currency?, tax_rate? } - payment_means?[]: { type, iban?, bic?, scheme? } - status?: draft | issued | paid | canceled ONE CALL IS THE WHOLE WRITE. This tool takes the invoice's status and both parties' company ids, so a create never needs a well_update_invoice after it: - The user asked to DRAFT an invoice → pass status: "draft" here. - You already found the company (well_query_records, well_get_entity) → pass its company_id on that party. Naming the party without its id re-resolves it, which can attach the invoice to the wrong company or create a duplicate one. Creating and then patching the same invoice writes twice and shows the user two confirmations for one action. Put the intent in this call.

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['issuer', 'receiver', 'reference_number', 'issue_date', 'currency', 'line_items'], 'properties': {'issuer': {'type': 'object', 'required': ['name'], 'properties': {'name': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Legal/company name of the party.'}, 'domain': {'type': 'string', 'description': 'Company domain, e.g. acme.com.'}, 'tax_id': {'type': 'string', 'description': 'VAT / tax id, if present on the invoice.'}, 'company_id': {'type': 'string', '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)$', 'description': 'An existing company in the workspace, bound directly — ALWAYS send this when you already know the company (e.g. you found it with well_query_records). Without it the party is re-resolved from name/domain/tax_id, which can attach the invoice to a different company or mint a duplicate.'}, 'tax_id_type': {'type': 'string', 'minLength': 1, 'description': 'Tax-id type backing tax_id, e.g. SIREN, EIN, VAT. Defaults to VAT when omitted.'}}}, 'status': {'enum': ['draft', 'issued', 'paid', 'canceled'], 'type': 'string', 'description': 'The invoice\'s lifecycle status. Set it here when the user asked for one ("draft an invoice") — do NOT create and then call well_update_invoice to change it. Omitted, the status is derived from the document type.'}, 'totals': {'type': 'object', 'required': ['grand_total'], 'properties': {'tax_total': {'type': 'number'}, 'grand_total': {'type': 'number'}, 'items_total': {'type': 'number'}}}, 'currency': {'type': 'string', 'description': 'ISO 4217 (3 letters).'}, 'due_date': {'type': 'string', 'description': 'ISO 8601 YYYY-MM-DD.'}, 'receiver': {'type': 'object', 'required': ['name'], 'properties': {'name': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Legal/company name of the party.'}, 'domain': {'type': 'string', 'description': 'Company domain, e.g. acme.com.'}, 'tax_id': {'type': 'string', 'description': 'VAT / tax id, if present on the invoice.'}, 'company_id': {'type': 'string', '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)$', 'description': 'An existing company in the workspace, bound directly — ALWAYS send this when you already know the company (e.g. you found it with well_query_records). Without it the party is re-resolved from name/domain/tax_id, which can attach the invoice to a different company or mint a duplicate.'}, 'tax_id_type': {'type': 'string', 'minLength': 1, 'description': 'Tax-id type backing tax_id, e.g. SIREN, EIN, VAT. Defaults to VAT when omitted.'}}}, 'issue_date': {'type': 'string', 'description': 'ISO 8601 YYYY-MM-DD.'}, 'line_items': {'type': 'array', 'items': {'type': 'object', 'required': ['name', 'unit_price'], 'properties': {'name': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Line description.'}, 'currency': {'type': 'string', 'description': 'ISO 4217; defaults to the invoice currency.'}, 'quantity': {'type': 'number'}, 'tax_rate': {'type': 'number', 'description': 'Tax rate as a percentage 0-100.'}, 'unit_price': {'type': 'number', 'description': 'Unit price (number, not string).'}}}, 'minItems': 1}, 'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.'}, 'payment_means': {'type': 'array', 'items': {'type': 'object', 'properties': {'bic': {'type': 'string'}, 'iban': {'type': 'string'}, 'type': {'enum': ['iban', 'card', 'cash', 'check', 'other'], 'type': 'string'}, 'scheme': {'type': 'string', 'description': 'e.g. SEPA, SWIFT — only honoured if a known scheme.'}}}}, 'conversation_id': {'type': 'string', '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.'}, 'idempotency_key': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.'}, 'reference_number': {'type': 'string', 'maxLength': 100, 'minLength': 1}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'error': {'type': 'string'}, 'success': {'type': 'boolean'}, 'invoice_id': {'type': 'string'}, 'document_id': {'type': 'string'}, 'payment_means': {'type': 'number'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'reference_number': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'invoice_item_count': {'type': 'number'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_create_person

Create person

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.

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['first_name'], 'properties': {'email': {'type': 'string', 'format': 'email', 'pattern': "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}, 'phone': {'type': 'string'}, 'job_title': {'type': 'string', 'maxLength': 100, 'description': 'Job title'}, 'last_name': {'anyOf': [{'type': 'string', 'maxLength': 255}, {'type': 'null'}], 'description': 'Last name (optional)'}, 'first_name': {'type': 'string', 'maxLength': 100, 'minLength': 1, 'description': 'First name (required)'}, 'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.'}, 'conversation_id': {'type': 'string', '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.'}, 'idempotency_key': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'error': {'type': 'string'}, 'success': {'type': 'boolean'}, 'full_name': {'type': 'string'}, 'person_id': {'type': 'string'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_create_statement_upload

Create statement upload slot

Mint a one-time, short-lived upload slot for a bank-statement file. Use this when the user has a statement file (PDF, or a large CSV/XML) to import; the file's bytes do not travel through the model. It returns a single-use upload URL + token; the client (or the user) POSTs the raw file bytes to that URL, and the resulting document enters the exact same import pipeline as an in-app upload (detection, dedup, promotion). This result renders a card in widget-capable hosts right away — do not wait for a poll to make it appear. One statement file per call: mint a separate slot for each file. Once the client has uploaded the file bytes, call well_get_statement_import_result with the document_id below one time to learn the outcome. The card polls the import result itself until it settles, so call that tool again only if the user asks. The token authorizes exactly ONE upload to this workspace and expires in 15 minutes. It is burned on first use — a second upload needs a new slot. It cannot be used for anything other than a statement upload. The response's document_id is PRE-ALLOCATED at mint time — the upload has not happened yet, and this exact id is what the document will carry once it does. A call to well_get_statement_import_result before the upload lands is a normal "not_found_yet", not an error.

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.'}, 'conversation_id': {'type': 'string', '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.'}, 'idempotency_key': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'error': {'type': 'string'}, 'token': {'type': 'string'}, 'success': {'type': 'boolean'}, 'upload_url': {'type': 'string'}, 'document_id': {'type': 'string', 'description': 'The pre-allocated document id — poll well_get_statement_import_result with it.'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'expires_in_seconds': {'type': 'number'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_delete_company

Delete company

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.

Destructive

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['company_id'], 'properties': {'company_id': {'type': 'string', '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)$', 'description': 'The UUID of the company to delete (required)'}, 'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.'}, 'conversation_id': {'type': 'string', '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.'}, 'idempotency_key': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'error': {'type': 'string'}, 'success': {'type': 'boolean'}, 'company_id': {'type': 'string'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_delete_invoice

Delete invoice

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.

Destructive

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['invoice_id'], 'properties': {'invoice_id': {'type': 'string', '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)$', 'description': 'The UUID of the invoice to delete'}, 'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.'}, 'conversation_id': {'type': 'string', '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.'}, 'idempotency_key': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'error': {'type': 'string'}, 'success': {'type': 'boolean'}, 'invoice_id': {'type': 'string', '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)$'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_delete_person

Delete person

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.

Destructive

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['person_id'], 'properties': {'person_id': {'type': 'string', '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)$', 'description': 'The UUID of the person to delete (required)'}, 'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.'}, 'conversation_id': {'type': 'string', '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.'}, 'idempotency_key': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'error': {'type': 'string'}, 'success': {'type': 'boolean'}, 'person_id': {'type': 'string'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_enqueue_invoice_fetch

Queue invoice collection

Queue invoice collection for named counterparties. This creates one durable backlog task per counterparty. The browser agent (a provider that carries a blueprint or a real portal URL) or the manual-upload route picks up each task later. Call this tool only after the user explicitly confirms the launch. Never call it on your own initiative. Get counterparty_company_ids from well_list_missing_invoices. This tool takes no period argument: a collection task belongs to a counterparty, not a month. A repeat call for a counterparty that already has a non-terminal task reuses that task (already_active: true) instead of creating a second one. provider.has_blueprint and provider.has_portal_url on an enqueued row state which counterparties a browser agent will visit (either one is enough), and which fall back to manual upload (neither). Creating the tasks launches nothing in the browser. Inside Well the tasks page and the chat card start and track them. From outside Well, hand the user the collect_url from well_preview_invoice_fetch to start the runs. That link never covers every enqueued counterparty. One link names at most 25 portals, so a counterparty past that ceiling appears in well_preview_invoice_fetch's collect_url_omits instead of on the link. A counterparty with provider: null has no portal at all and is routed to manual upload. A counterparty with an address the link cannot carry appears in collect_url_unaddressable. Never tell the user the link covers a counterparty it does not name. Use well_preview_invoice_fetch first to see what a fetch would cover — it is read-only and launches nothing. Use well_enqueue_close_invoice_fetch instead of this tool when you are inside a close run: it is the same action, scoped to that run's flow_run_id. Use this tool outside a close run. Report the counts back to the user: how many tasks were enqueued, how many of those were already active, and how many counterparties were skipped, with each skip's reason.

Idempotent

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['counterparty_company_ids'], 'properties': {'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.'}, 'conversation_id': {'type': 'string', '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.'}, 'idempotency_key': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.'}, 'counterparty_company_ids': {'type': 'array', 'items': {'type': 'string', '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)$'}, 'maxItems': 200, 'minItems': 1, 'description': 'Counterparty companies to queue collection for, from well_list_missing_invoices.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'error': {'type': 'string'}, 'skipped': {'type': 'array', 'items': {'type': 'object', 'required': ['company_id', 'reason'], 'properties': {'reason': {'enum': ['company_not_found_in_workspace', 'not_owned_by_current_user'], 'type': 'string'}, 'company_id': {'type': 'string', '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)$'}}, 'additionalProperties': False}}, 'success': {'type': 'boolean'}, 'enqueued': {'type': 'array', 'items': {'type': 'object', 'required': ['company_id', 'task_id', 'task_title', 'provider', 'already_active'], 'properties': {'task_id': {'type': 'string', '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)$'}, 'provider': {'anyOf': [{'type': 'object', 'required': ['id', 'name', 'slug', 'url', 'logo_url', 'countries', 'has_blueprint', 'has_portal_url'], 'properties': {'id': {'type': 'string', '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)$'}, 'url': {'type': 'string'}, 'name': {'type': 'string'}, 'slug': {'type': 'string'}, 'logo_url': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'countries': {'type': 'array', 'items': {'type': 'string'}}, 'has_blueprint': {'type': 'boolean'}, 'has_portal_url': {'type': 'boolean'}}, 'additionalProperties': False}, {'type': 'null'}]}, 'company_id': {'type': 'string', '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)$'}, 'task_title': {'type': 'string'}, 'already_active': {'type': 'boolean'}}, 'additionalProperties': False}}, 'skipped_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'enqueued_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0, 'description': 'Rows in enqueued — created or reused.'}, 'refusal_reason': {'type': 'string', 'description': 'The WellError code when the write is refused.'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'already_active_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0, 'description': 'Of enqueued_count, how many reused an existing task rather than creating one.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_get_accounting_settings

Get accounting settings

Read the workspace's accounting settings and their provenance WITHOUT showing the user anything: country of incorporation, incorporation date, tax ID, fiscal year start, base currency, and accounting framework. Each field carries its value, where the value came from, and the stored "Suggested" fills. This draws nothing on the user's screen and asks for no confirmation. Use it ONLY for a silent CHECK the model acts on itself: the close-books step deciding whether the fiscal year start and the base currency are already present and trusted before it moves on, a step that needs the current framework or start month to compute something. Read the fields and act in the same turn — there is no card and no click to wait on. ⚠️ To have the USER review or CONFIRM the settings, call `well_show_accounting_settings` INSTEAD — that one draws the card the user completes and confirms. This tool cannot draw one, so a confirm step run here leaves the user with nothing to act on.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which."}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'error': {'type': 'string'}, 'success': {'type': 'boolean'}, 'settings': {'type': 'object', 'required': ['country', 'base_currency', 'accounting_framework', 'fiscal_year_start_month', 'fiscal_year_start_month_source', 'fiscal_year_start_locked', 'first_fiscal_year_start_date', 'first_fiscal_year_start_source', 'coa_confirmed', 'coa_confirmed_source', 'field_provenance', 'incorporation_date', 'registered_name', 'trade_name', 'registered_value', 'domain', 'business_type', 'address', 'own_company_id', 'created_at', 'updated_at', 'tax_id'], 'properties': {'domain': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'tax_id': {'type': 'object', 'required': ['present', 'source', 'suggestion_available'], 'properties': {'source': {'anyOf': [{'enum': ['ai', 'registry', 'derived', 'user'], 'type': 'string'}, {'type': 'null'}]}, 'present': {'type': 'boolean'}, 'suggestion_available': {'type': 'boolean'}}, 'additionalProperties': False}, 'address': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'country': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'created_at': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'trade_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'updated_at': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'base_currency': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'business_type': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'coa_confirmed': {'anyOf': [{'type': 'boolean'}, {'type': 'null'}]}, 'own_company_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'registered_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'field_provenance': {'anyOf': [{'type': 'object', 'properties': {'tax_id': {'type': 'object', 'required': ['source', 'confidence', 'reason', 'recorded_at'], 'properties': {'reason': {'anyOf': [{'enum': ['registry_match', 'email_domain', 'country_default', 'invoice_header', 'agent_setup'], 'type': 'string'}, {'type': 'null'}]}, 'source': {'enum': ['ai', 'registry', 'derived', 'user'], 'type': 'string'}, 'confidence': {'anyOf': [{'type': 'number', 'maximum': 1, 'minimum': 0}, {'type': 'null'}]}, 'recorded_at': {'type': 'string'}}, 'additionalProperties': False}, 'country': {'type': 'object', 'required': ['source', 'confidence', 'reason', 'recorded_at'], 'properties': {'reason': {'anyOf': [{'enum': ['registry_match', 'email_domain', 'country_default', 'invoice_header', 'agent_setup'], 'type': 'string'}, {'type': 'null'}]}, 'source': {'enum': ['ai', 'registry', 'derived', 'user'], 'type': 'string'}, 'confidence': {'anyOf': [{'type': 'number', 'maximum': 1, 'minimum': 0}, {'type': 'null'}]}, 'recorded_at': {'type': 'string'}}, 'additionalProperties': False}, 'base_currency': {'type': 'object', 'required': ['source', 'confidence', 'reason', 'recorded_at'], 'properties': {'reason': {'anyOf': [{'enum': ['registry_match', 'email_domain', 'country_default', 'invoice_header', 'agent_setup'], 'type': 'string'}, {'type': 'null'}]}, 'source': {'enum': ['ai', 'registry', 'derived', 'user'], 'type': 'string'}, 'confidence': {'anyOf': [{'type': 'number', 'maximum': 1, 'minimum': 0}, {'type': 'null'}]}, 'recorded_at': {'type': 'string'}}, 'additionalProperties': False}, 'incorporation_date': {'type': 'object', 'required': ['source', 'confidence', 'reason', 'recorded_at'], 'properties': {'reason': {'anyOf': [{'enum': ['registry_match', 'email_domain', 'country_default', 'invoice_header', 'agent_setup'], 'type': 'string'}, {'type': 'null'}]}, 'source': {'enum': ['ai', 'registry', 'derived', 'user'], 'type': 'string'}, 'confidence': {'anyOf': [{'type': 'number', 'maximum': 1, 'minimum': 0}, {'type': 'null'}]}, 'recorded_at': {'type': 'string'}}, 'additionalProperties': False}, 'accounting_framework': {'type': 'object', 'required': ['source', 'confidence', 'reason', 'recorded_at'], 'properties': {'reason': {'anyOf': [{'enum': ['registry_match', 'email_domain', 'country_default', 'invoice_header', 'agent_setup'], 'type': 'string'}, {'type': 'null'}]}, 'source': {'enum': ['ai', 'registry', 'derived', 'user'], 'type': 'string'}, 'confidence': {'anyOf': [{'type': 'number', 'maximum': 1, 'minimum': 0}, {'type': 'null'}]}, 'recorded_at': {'type': 'string'}}, 'additionalProperties': False}, 'fiscal_year_start_month': {'type': 'object', 'required': ['source', 'confidence', 'reason', 'recorded_at'], 'properties': {'reason': {'anyOf': [{'enum': ['registry_match', 'email_domain', 'country_default', 'invoice_header', 'agent_setup'], 'type': 'string'}, {'type': 'null'}]}, 'source': {'enum': ['ai', 'registry', 'derived', 'user'], 'type': 'string'}, 'confidence': {'anyOf': [{'type': 'number', 'maximum': 1, 'minimum': 0}, {'type': 'null'}]}, 'recorded_at': {'type': 'string'}}, 'additionalProperties': False}}, 'additionalProperties': False}, {'type': 'null'}]}, 'registered_value': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'incorporation_date': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'accounting_framework': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'coa_confirmed_source': {'anyOf': [{'type': 'string', 'const': 'user'}, {'type': 'null'}]}, 'fiscal_year_start_month': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'fiscal_year_start_locked': {'type': 'boolean'}, 'first_fiscal_year_start_date': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'first_fiscal_year_start_source': {'anyOf': [{'enum': ['derived', 'user'], 'type': 'string'}, {'type': 'null'}]}, 'fiscal_year_start_month_source': {'anyOf': [{'enum': ['derived', 'registry', 'user'], 'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}, 'next_step': {'type': 'string', 'description': 'What to do with the card this result renders. Added by the dispatcher when the card asks for a click.'}, 'suggestions': {'type': 'object', 'properties': {'tax_id': {'type': 'array', 'items': {'type': 'object', 'required': ['value', 'label', 'source', 'reason', 'confidence', 'country'], 'properties': {'label': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'value': {'type': 'string'}, 'reason': {'anyOf': [{'enum': ['registry_match', 'email_domain', 'country_default', 'invoice_header', 'agent_setup'], 'type': 'string'}, {'type': 'null'}]}, 'source': {'enum': ['ai', 'registry', 'derived', 'user'], 'type': 'string'}, 'country': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'confidence': {'anyOf': [{'type': 'number', 'maximum': 1, 'minimum': 0}, {'type': 'null'}]}, 'tax_id_type': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}}, 'country': {'type': 'array', 'items': {'type': 'object', 'required': ['value', 'label', 'source', 'reason', 'confidence', 'country'], 'properties': {'label': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'value': {'type': 'string'}, 'reason': {'anyOf': [{'enum': ['registry_match', 'email_domain', 'country_default', 'invoice_header', 'agent_setup'], 'type': 'string'}, {'type': 'null'}]}, 'source': {'enum': ['ai', 'registry', 'derived', 'user'], 'type': 'string'}, 'country': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'confidence': {'anyOf': [{'type': 'number', 'maximum': 1, 'minimum': 0}, {'type': 'null'}]}, 'tax_id_type': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}}, 'base_currency': {'type': 'array', 'items': {'type': 'object', 'required': ['value', 'label', 'source', 'reason', 'confidence', 'country'], 'properties': {'label': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'value': {'type': 'string'}, 'reason': {'anyOf': [{'enum': ['registry_match', 'email_domain', 'country_default', 'invoice_header', 'agent_setup'], 'type': 'string'}, {'type': 'null'}]}, 'source': {'enum': ['ai', 'registry', 'derived', 'user'], 'type': 'string'}, 'country': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'confidence': {'anyOf': [{'type': 'number', 'maximum': 1, 'minimum': 0}, {'type': 'null'}]}, 'tax_id_type': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}}, 'incorporation_date': {'type': 'array', 'items': {'type': 'object', 'required': ['value', 'label', 'source', 'reason', 'confidence', 'country'], 'properties': {'label': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'value': {'type': 'string'}, 'reason': {'anyOf': [{'enum': ['registry_match', 'email_domain', 'country_default', 'invoice_header', 'agent_setup'], 'type': 'string'}, {'type': 'null'}]}, 'source': {'enum': ['ai', 'registry', 'derived', 'user'], 'type': 'string'}, 'country': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'confidence': {'anyOf': [{'type': 'number', 'maximum': 1, 'minimum': 0}, {'type': 'null'}]}, 'tax_id_type': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}}, 'accounting_framework': {'type': 'array', 'items': {'type': 'object', 'required': ['value', 'label', 'source', 'reason', 'confidence', 'country'], 'properties': {'label': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'value': {'type': 'string'}, 'reason': {'anyOf': [{'enum': ['registry_match', 'email_domain', 'country_default', 'invoice_header', 'agent_setup'], 'type': 'string'}, {'type': 'null'}]}, 'source': {'enum': ['ai', 'registry', 'derived', 'user'], 'type': 'string'}, 'country': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'confidence': {'anyOf': [{'type': 'number', 'maximum': 1, 'minimum': 0}, {'type': 'null'}]}, 'tax_id_type': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}}, 'fiscal_year_start_month': {'type': 'array', 'items': {'type': 'object', 'required': ['value', 'label', 'source', 'reason', 'confidence', 'country'], 'properties': {'label': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'value': {'type': 'string'}, 'reason': {'anyOf': [{'enum': ['registry_match', 'email_domain', 'country_default', 'invoice_header', 'agent_setup'], 'type': 'string'}, {'type': 'null'}]}, 'source': {'enum': ['ai', 'registry', 'derived', 'user'], 'type': 'string'}, 'country': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'confidence': {'anyOf': [{'type': 'number', 'maximum': 1, 'minimum': 0}, {'type': 'null'}]}, 'tax_id_type': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}}}, 'additionalProperties': False}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_get_connector_coverage

Get connector coverage

Read what a workspace has CONNECTED and what it can connect. This draws nothing on the user's screen. Use it for every coverage CHECK: a data skill confirming a bank is connected before it measures anything, a step that needs a `workspace_connector_id`, a health read on a connector the user asked about. Read each row's state and hand the answer back in your own words, in the same turn — there is no card to wait on here, and no acknowledgement to ask for. ⚠️ FOR A CONNECT STEP, CALL `well_list_connectors` INSTEAD. Same scope arguments, same rows, and its result draws the card with the install links and the Continue the user clicks. This tool cannot draw one, so a connect step run here leaves the user with prose and no way to act. Do NOT read workspace_connectors records to work out connection coverage; this tool is that answer. The rows are the rows of `well_list_connectors`, field for field. Its description carries the field reference, and this description does not repeat it.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'q': {'type': 'string', 'maxLength': 120, 'minLength': 1, 'description': 'Name search across the full catalog (e.g. a specific bank). Omit for the curated, matched-first view.'}, 'kind': {'enum': ['bank', 'accounting', 'invoicing', 'upload_surface', 'storage'], 'type': 'string', 'description': 'Scope the card server-side. Three financial domains: "bank" (every bank and neobank, including the long tail of open-banking institutions, plus the platforms that hold an account like Qonto and Pennylane — never a payroll or billing tool that merely reports transactions), "accounting", and "invoicing". Plus two scopes the server resolves from display categories rather than from a financial domain: "upload_surface", the places invoices ARRIVE (mailboxes, messaging apps, file drives), and "storage", the drives Well FILES INTO (Google Drive, Dropbox, OneDrive). The last two are opposite directions on the same drives, so a workspace can hold both connections and each is offered on its own card. Use this for a connect-a-bank, a connect-where-invoices-arrive or a connect-where-Well-files step instead of filtering the default view yourself. Omit for every connectable connector.'}, 'limit': {'type': 'integer', 'maximum': 100, 'minimum': 1, 'description': 'Max connectors to return (1-100, default 50).'}, 'offset': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0, 'description': 'Number of connectors to skip, for paging (default 0).'}, 'country': {'enum': ['AD', 'AE', 'AF', 'AG', 'AI', 'AL', 'AM', 'AO', 'AQ', 'AR', 'AS', 'AT', 'AU', 'AW', 'AX', 'AZ', 'BA', 'BB', 'BD', 'BE', 'BF', 'BG', 'BH', 'BI', 'BJ', 'BL', 'BM', 'BN', 'BO', 'BQ', 'BR', 'BS', 'BT', 'BV', 'BW', 'BY', 'BZ', 'CA', 'CC', 'CD', 'CF', 'CG', 'CH', 'CI', 'CK', 'CL', 'CM', 'CN', 'CO', 'CR', 'CU', 'CV', 'CW', 'CX', 'CY', 'CZ', 'DE', 'DJ', 'DK', 'DM', 'DO', 'DZ', 'EC', 'EE', 'EG', 'EH', 'ER', 'ES', 'ET', 'FI', 'FJ', 'FK', 'FM', 'FO', 'FR', 'GA', 'GB', 'GD', 'GE', 'GF', 'GG', 'GH', 'GI', 'GL', 'GM', 'GN', 'GP', 'GQ', 'GR', 'GS', 'GT', 'GU', 'GW', 'GY', 'HK', 'HM', 'HN', 'HR', 'HT', 'HU', 'ID', 'IE', 'IL', 'IM', 'IN', 'IO', 'IQ', 'IR', 'IS', 'IT', 'JE', 'JM', 'JO', 'JP', 'KE', 'KG', 'KH', 'KI', 'KM', 'KN', 'KP', 'KR', 'KW', 'KY', 'KZ', 'LA', 'LB', 'LC', 'LI', 'LK', 'LR', 'LS', 'LT', 'LU', 'LV', 'LY', 'MA', 'MC', 'MD', 'ME', 'MF', 'MG', 'MH', 'MK', 'ML', 'MM', 'MN', 'MO', 'MP', 'MQ', 'MR', 'MS', 'MT', 'MU', 'MV', 'MW', 'MX', 'MY', 'MZ', 'NA', 'NC', 'NE', 'NF', 'NG', 'NI', 'NL', 'NO', 'NP', 'NR', 'NU', 'NZ', 'OM', 'PA', 'PE', 'PF', 'PG', 'PH', 'PK', 'PL', 'PM', 'PN', 'PR', 'PS', 'PT', 'PW', 'PY', 'QA', 'RE', 'RO', 'RS', 'RU', 'RW', 'SA', 'SB', 'SC', 'SD', 'SE', 'SG', 'SH', 'SI', 'SJ', 'SK', 'SL', 'SM', 'SN', 'SO', 'SR', 'SS', 'ST', 'SV', 'SX', 'SY', 'SZ', 'TC', 'TD', 'TF', 'TG', 'TH', 'TJ', 'TK', 'TL', 'TM', 'TN', 'TO', 'TR', 'TT', 'TV', 'TW', 'TZ', 'UA', 'UG', 'UM', 'US', 'UY', 'UZ', 'VA', 'VC', 'VE', 'VG', 'VI', 'VN', 'VU', 'WF', 'WS', 'YE', 'YT', 'ZA', 'ZM', 'ZW'], 'type': 'string', 'description': 'The company\'s country as an ISO 3166-1 alpha-2 code (e.g. "FR"). When set, the connectors that serve that country sort first, then the ones that serve its region, then the rest — the order only, no row is dropped. Use it on a connect-a-bank step so the banks that fit the company appear first; take it from the workspace identity\'s country. Omit when the country is unknown, and the order is left unchanged.'}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which."}, 'from_selection': {'type': 'boolean', 'const': True, 'description': "Scope the card to the connectors behind the counterparties the user picked on the missing-invoices card in this conversation, each installable one pre-checked. Use it for the connect step that FOLLOWS a vendor pick. It returns those vendors' connectors and NOTHING else: a picked connector that brings no invoices in is dropped, and no accounting or invoicing tool the user did not pick is offered here: that offer is its own step, scoped with `kind`. Cannot be combined with `q` or `kind`: those name a catalog to browse, and this names a set already decided. Returns an empty list when this conversation holds no pick for this workspace, or when no picked counterparty matched a connector."}, 'conversation_id': {'type': 'string', '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.'}, 'include_unsent_counts': {'type': 'boolean', 'const': True, 'description': "Add the top-level `unsent_document_counts`: every tool Well forwards this workspace's documents to, each with how many documents it has not received yet. That array is the whole answer — it holds every one of the workspace's outbound connections, whatever catalog page was requested, and the rows carry no count at all. Off by default, because it costs an extra read. The figure is the workspace's whole backlog, not a period's."}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['install_all_url', 'install_all_omitted', 'success'], 'properties': {'error': {'type': 'string'}, 'limit': {'type': 'number', 'description': 'The page size that was REQUESTED. The catalog may return fewer.'}, 'scope': {'enum': ['catalog', 'bank', 'accounting', 'invoicing', 'upload_surface', 'storage', 'picked_vendors'], 'type': 'string', 'description': "What this result is a list OF: the requested kind, the picked vendors' connectors, or the curated catalog when neither was asked for. The card words itself from this, so it never describes the rows as a domain that was not requested."}, 'total': {'type': 'number', 'description': 'Every connector matching the query, across all pages — NOT the length of `connectors`.'}, 'offset': {'type': 'number', 'description': 'How many catalog rows this page skipped.'}, 'success': {'type': 'boolean'}, 'row_count': {'type': 'number', 'description': 'How many rows this result puts ON THE CARD, prepended rows included. `0` on a `picked_vendors` scope means the pick has no connector behind it that can bring an invoice in: the card carries nothing to tick, so say so in half a sentence and move on. Not a paging cursor — `page_count` is.'}, 'connectors': {'type': 'array', 'items': {'type': 'object', 'required': ['service_id', 'name', 'category_id', 'status', 'direction', 'data_domains', 'invoice_source', 'reason', 'logo_url', 'popularity_score', 'is_matched', 'is_selected', 'match_score', 'is_connected', 'connection_status', 'workspace_connector_id', 'last_successful_sync_at', 'sync_in_progress', 'is_preselected', 'install_url', 'countries'], 'properties': {'name': {'type': 'string'}, 'reason': {'enum': ['catalog', 'picked_vendor'], 'type': 'string'}, 'status': {'type': 'string'}, 'logo_url': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'countries': {'anyOf': [{'type': 'array', 'items': {'type': 'string'}}, {'type': 'null'}]}, 'direction': {'type': 'string'}, 'is_matched': {'type': 'boolean'}, 'service_id': {'type': 'string'}, 'category_id': {'type': 'string'}, 'install_url': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'is_selected': {'type': 'boolean'}, 'match_score': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'data_domains': {'anyOf': [{'type': 'array', 'items': {'enum': ['bank', 'accounting', 'invoicing'], 'type': 'string'}}, {'type': 'null'}]}, 'is_connected': {'type': 'boolean'}, 'invoice_source': {'type': 'boolean'}, 'is_preselected': {'type': 'boolean'}, 'popularity_score': {'anyOf': [{'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, {'type': 'null'}]}, 'sync_in_progress': {'type': 'boolean'}, 'connection_status': {'anyOf': [{'enum': ['enabled', 'processing', 'error', 'need_reconnect', 'to_configure', 'disabled'], 'type': 'string'}, {'type': 'null'}]}, 'workspace_connector_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'last_successful_sync_at': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}}, 'page_count': {'type': 'number', 'description': "The catalog page's own length, and the ONLY safe paging cursor: advance by `offset + page_count`. `connectors` can be LONGER — on the first page of an unsearched browse the workspace's already-connected rows are prepended so they cannot be lost to the catalog's ordering — so paging by the array's length silently skips exactly that many catalog rows on every later request."}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'install_all_url': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "One link that installs every installable connector in this result. Null when the result offers nothing to install, or when its scope names a set the reader has not chosen. When it is non-null it is the ONLY install link the answer offers — do not list the rows' own install_url beside it. When it is null, the rows' own install_url is the offer instead."}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'install_all_omitted': {'type': 'array', 'items': {'type': 'string'}, 'description': 'The service ids install_all_url could not carry, because one link names a bounded number of connectors. Offer these rows their own install_url instead of promising the batch link covers them.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}, 'unsent_document_counts': {'type': 'array', 'items': {'type': 'object', 'required': ['service_id', 'name', 'workspace_connector_id', 'unsent_document_count', 'unsent_document_count_is_upper_bound'], 'properties': {'name': {'type': 'string'}, 'service_id': {'type': 'string'}, 'unsent_document_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'workspace_connector_id': {'type': 'string'}, 'unsent_document_count_is_upper_bound': {'type': 'boolean'}}, 'additionalProperties': False}, 'description': "Every tool this workspace forwards documents to, each with the documents it has not received yet, biggest backlog first. Present only when `include_unsent_counts` was set. THIS IS THE ONLY PLACE THE BACKLOG IS REPORTED: it is not a page, it carries the workspace's whole set of outbound connections whether or not the requested catalog page holds their rows, and the catalog rows carry no count. An empty array means the workspace forwards to nothing; an absent field means nothing was measured. `unsent_document_count_is_upper_bound: true` means a document filter applies to that connection, so the count is a maximum and reads as `up to <n>`. Every count is read off Well's own forward record, so it measures what Well wrote down rather than what the tool confirmed. Name a tool by its `name`. An entry reading `0` is a tool that is up to date: say nothing about it."}, 'picked_vendors_filtered': {'type': 'number', 'description': "How many of the picked vendors' connectors were dropped for bringing no invoices in. Present on the `picked_vendors` scope only. Above zero means the card is SHORTER than the pick: say that those vendors' tools cannot deliver an invoice, rather than letting the gap read as a pick the user never made."}}, 'additionalProperties': False}

well_get_customer_einvoicing_details

Get customer e-invoicing details

Get one CUSTOMER's e-invoicing identity — the registry values an invoice to that customer is routed on, or that a period aggregate for it is reported under. Use this when the question is about the party the workspace BILLS: "can we invoice this customer electronically", "what is their SIREN / VAT number / billing address", "what do we still need before we can route this invoice". Read `well_get_own_company` instead when the question is about which company the workspace ITSELF is. Returns `customer_kind` ("company" routes an invoice, "individual" reports a sale, absent when the customer's type is not stated), `customer` (the composite: `company_id`, `name`, `subline`, `identified`), `fields` (one entry per detail the graph can hold, each with its `value` and `provenance` when one is held), `unstorable_fields` (details this flow needs that no column holds yet), `hints` and `connectors_url`. A field listed in `unstorable_fields` is not a gap the user can close — say plainly that Well cannot store it yet, and never ask for it. A `fields` entry with no `value` IS answerable and is what still blocks the route. When the token authorizes one workspace, call this directly — no other tool call is needed first. When it authorizes several, this read will not guess which one you mean: pass `workspace_id` on the call.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['company_id'], 'properties': {'company_id': {'type': 'string', 'description': "The customer's public company UUID (the `company_id` field on a companies record)."}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which."}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['customer', 'fields', 'unstorable_fields', 'success'], 'properties': {'error': {'type': 'string'}, 'hints': {'type': 'array', 'items': {'type': 'object', 'required': ['detected_gap'], 'properties': {'field': {'type': 'string'}, 'cta_link': {'type': 'string', 'format': 'uri'}, 'severity': {'enum': ['info', 'warn'], 'type': 'string'}, 'signal_id': {'type': 'string'}, 'detected_gap': {'type': 'string'}}, 'additionalProperties': False}}, 'fields': {'type': 'array', 'items': {'type': 'object', 'required': ['field'], 'properties': {'field': {'enum': ['legal_name', 'siren', 'billed_establishment', 'postal_address', 'vat_number', 'einvoicing_address', 'buyer_reference', 'customer_type', 'place_of_supply_country', 'supply_category', 'vat_rate', 'vat_point_basis'], 'type': 'string'}, 'score': {'type': 'number'}, 'value': {'type': 'string'}, 'country': {'type': 'string'}, 'options': {'type': 'array', 'items': {'type': 'object', 'required': ['value', 'label'], 'properties': {'note': {'type': 'string'}, 'label': {'type': 'string'}, 'score': {'type': 'number'}, 'value': {'type': 'string'}, 'country': {'type': 'string'}}, 'additionalProperties': False}}, 'provenance': {'enum': ['registry', 'derived', 'user', 'ai'], 'type': 'string'}, 'suggestions': {'type': 'array', 'items': {'type': 'object', 'required': ['value', 'label'], 'properties': {'note': {'type': 'string'}, 'label': {'type': 'string'}, 'score': {'type': 'number'}, 'value': {'type': 'string'}, 'country': {'type': 'string'}}, 'additionalProperties': False}}, 'options_group': {'enum': ['countries', 'schemes', 'customer_types', 'supply_categories'], 'type': 'string'}}, 'additionalProperties': False}}, 'success': {'type': 'boolean'}, 'customer': {'anyOf': [{'type': 'object', 'required': ['company_id', 'name', 'subline', 'identified'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'subline': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'company_id': {'type': 'string'}, 'identified': {'type': 'boolean'}}, 'additionalProperties': False}, {'type': 'null'}]}, 'error_reason': {'enum': ['no_workspace', 'read_failed'], 'type': 'string'}, 'customer_kind': {'enum': ['company', 'individual'], 'type': 'string'}, 'connectors_url': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'unstorable_fields': {'type': 'array', 'items': {'enum': ['legal_name', 'siren', 'billed_establishment', 'postal_address', 'vat_number', 'einvoicing_address', 'buyer_reference', 'customer_type', 'place_of_supply_country', 'supply_category', 'vat_rate', 'vat_point_basis'], 'type': 'string'}}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_get_design_tokens

Get design tokens

Get Well's colours, shape and type vocabulary, so a view you compose for Well data looks like Well rather than a generic page. Call this ONLY when you are about to render something yourself — an HTML artifact, a report, a chart you are drawing. You do not need it to answer in prose or in a markdown table. Do NOT use it to restyle a card a Well tool already drew. Where a tool ships its own card the host renders it, and a second styled copy of the same figures is a duplicate, not an improvement. Returns `colors` (roles, not raw token names — `page_background`, `card_surface`, `text_primary`, `accent`, `positive`, `negative`, ...), `series` (categorical chart colours in the order to consume them), `shape` (corner radius and gap), `fonts`, and `color_scheme`, which tells you which ground to compose against. When it is absent the stylesheet did not declare one — pick a ground from `page_background` rather than assuming. Values come from the same token package the Well app, the browser extension and the tool cards compile against, so they cannot drift from the product.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Optional: this tool describes the token itself rather than one workspace's data, so omitting it returns the same answer."}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['colors', 'series', 'shape', 'fonts', 'success'], 'properties': {'error': {'type': 'string'}, 'fonts': {'type': 'object', 'propertyNames': {'type': 'string'}, 'additionalProperties': {'type': 'string'}}, 'hints': {'type': 'array', 'items': {'type': 'object', 'required': ['detected_gap', 'suggested_action', 'severity'], 'properties': {'severity': {'enum': ['warn', 'info'], 'type': 'string'}, 'detected_gap': {'type': 'string'}, 'suggested_action': {'type': 'string'}}, 'additionalProperties': False}}, 'shape': {'type': 'object', 'propertyNames': {'type': 'string'}, 'additionalProperties': {'type': 'string'}}, 'colors': {'type': 'object', 'propertyNames': {'type': 'string'}, 'additionalProperties': {'type': 'string'}}, 'series': {'type': 'array', 'items': {'type': 'string'}}, 'success': {'type': 'boolean'}, 'color_scheme': {'enum': ['dark', 'light'], 'type': 'string'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_get_entity

Get entity (with sub-resources)

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.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['root', 'id'], 'properties': {'id': {'type': 'string', 'description': "The entity's public UUID (the value of its *_id field, e.g. company_id)"}, 'root': {'type': 'string', 'description': 'Entity type, e.g. companies | people | invoices | transactions'}, 'depth': {'type': 'integer', 'maximum': 3, 'minimum': 1, 'description': 'Relation-nesting boundary 1-3 (default 1).'}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. This read reports one workspace's own data. Omit it and the token's primary workspace answers, which may not be the one you mean; the result names the workspace that did."}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['found', 'entity', 'success'], 'properties': {'depth': {'type': 'number'}, 'error': {'type': 'string'}, 'found': {'type': 'boolean'}, 'entity': {'anyOf': [{'type': 'object', 'propertyNames': {'type': 'string'}, 'additionalProperties': {}}, {'type': 'null'}]}, 'success': {'type': 'boolean'}, 'columnMeta': {'type': 'object', 'description': "Per-column field meaning ({context, enrichment}) for documented columns — read this to interpret the entity's values.", 'propertyNames': {'type': 'string'}, 'additionalProperties': {'type': 'object', 'properties': {'context': {'type': 'string'}, 'enrichment': {'type': 'string'}}, 'additionalProperties': False}}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'fields_selected': {'type': 'number'}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_get_graph

Get workspace graph

Draw the workspace's context graph — its companies, people, accounts, transactions and connectors, and the connections between them — as an interactive canvas the user can orbit, zoom and hover. Use it when someone asks to see how their business data connects, wants a picture of the workspace, or asks what a company or person is linked to. Narrow the drawing with perspective ("contacts", "money", "accounting"), time_window, min_degree (thin a dense workspace to its hubs) and company_cap. The card renders the graph itself. This tool's text result reports only the counts, so say what the shape shows rather than listing nodes. When at_company_cap is true the drawing holds as many companies as the cap allows and the workspace may hold more — say the view is capped rather than describing it as the whole graph. This tool reads only — it changes nothing.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'min_degree': {'enum': [0, 1, 2, 5], 'type': 'number', 'description': 'Drop nodes with fewer than this many connections. Raise it to thin a dense workspace down to its hubs; 0 keeps every node.'}, 'company_cap': {'enum': [5, 10, 20, 30, 50], 'type': 'number', 'description': "Cap the number of company nodes drawn. Omit for the server's unbounded default."}, 'perspective': {'enum': ['all', 'contacts', 'money', 'accounting'], 'type': 'string', 'description': 'Which slice of the graph to draw. "all" is everything; "contacts" is people and companies; "money" is transactions and accounts; "accounting" is the ledger side. Defaults to the server\'s own default when omitted.'}, 'time_window': {'enum': ['30d', '90d', '1y', 'all'], 'type': 'string', 'description': "How far back to reach for the underlying records. Defaults to the server's own default when omitted."}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which."}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'error': {'type': 'string'}, 'success': {'type': 'boolean'}, 'edge_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Connections between the shipped nodes.'}, 'node_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Nodes the server actually shipped, after every filter.'}, 'company_cap': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'The company cap the server applied, when one was.'}, 'failed_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Open work that cannot progress on its own: stuck tasks and errored connectors.'}, 'at_company_cap': {'type': 'boolean', 'description': 'True when the drawing holds as many company nodes as the cap allowed, so the workspace may hold companies it does not show. It is not a count of what was left out — the projection carries no dropped-row signal.'}, 'own_company_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "The workspace's own company node, when one is resolved."}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'processing_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Open work that may still change the scene: queued or running tasks, plus connectors mid-sync.'}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_get_investment_holdings

Get investment holdings

Get the live holdings/positions (what's currently held and its value) for a connected Plaid investment account — brokerage, IRA, 401k, etc. WORKFLOW: 1. well_list_connectors() → pick the ENABLED Plaid connector (connection_status: "enabled") and read its workspace_connector_id directly off the row. 2. well_get_investment_holdings({ workspace_connector_id }) → the current holdings, fetched fresh from Plaid on every call (never stored/stale data). Only works on Plaid connectors that support the investments product — not the MCP-transport connector-tool-passthrough tools (well_list_connector_tools / well_invoke_connector_tool), and not for investment transactions (buy/sell/dividend/fee), which are queryable as ordinary rows via well_query_records on the transactions root instead.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['workspace_connector_id'], 'properties': {'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. This read reports one workspace's own data. Omit it and the token's primary workspace answers, which may not be the one you mean; the result names the workspace that did."}, 'conversation_id': {'type': 'string', '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.'}, 'workspace_connector_id': {'type': 'string', 'minLength': 1, 'description': "The connected Plaid provider's workspace_connector_id (from well_list_connectors)."}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'error': {'type': 'string'}, 'success': {'type': 'boolean'}, 'holdings': {'type': 'array', 'items': {'type': 'object', 'required': ['account_id', 'quantity', 'institution_price', 'institution_value', 'cost_basis', 'currency'], 'properties': {'currency': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'quantity': {'type': 'number'}, 'security': {'type': 'object', 'required': ['name', 'ticker_symbol', 'type'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'type': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'ticker_symbol': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}, 'account_id': {'type': 'string'}, 'cost_basis': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'institution_price': {'type': 'number'}, 'institution_value': {'type': 'number'}}, 'additionalProperties': False}}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_get_own_company

Get own company

Get which company the workspace itself is: the confirmed own-company anchor (`anchor`) and any detected companies not yet confirmed as it (`candidates`). Use this whenever a question turns on "mine" versus "theirs" — my payables, my receivables, invoices I owe, what we billed — and then filter by the `company_id` this returns. Never decide which records are the workspace's own by comparing a company NAME: the same legal entity appears under several labels (a registered name, a trade name, a bank-issued label), so a name filter silently drops rows. Returns `anchor` (`company_id`, `registered_name`, `trade_name`) or null when the workspace has not resolved one yet, and `candidates` (each with `company_id`, names, `role`, `confidence_score`, `state`). `anchor: null` means the workspace has no confirmed own company. Say so plainly and do not promote a candidate to the anchor yourself — a candidate is a detection, not a decision, and confirming one is a user action. ⚠️ TO ASK THE USER WHICH COMPANY on a card so they can pick or search for it, call `well_show_company_candidates` INSTEAD: it draws a tile per candidate with a registry search and waits for the click. This read draws nothing. Registry tax ids and registered addresses are deliberately not returned. Call this directly — no other tool call is needed first. Both the anchor and the candidates are read from the same workspace this call is scoped to.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. This read reports one workspace's own data. Omit it and the token's primary workspace answers, which may not be the one you mean; the result names the workspace that did."}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['anchor', 'candidates', 'success'], 'properties': {'error': {'type': 'string'}, 'anchor': {'anyOf': [{'type': 'object', 'required': ['company_id', 'registered_name', 'trade_name'], 'properties': {'company_id': {'type': 'string'}, 'trade_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'registered_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}, {'type': 'null'}]}, 'success': {'type': 'boolean'}, 'candidates': {'type': 'array', 'items': {'type': 'object', 'required': ['candidate_id', 'company_id', 'registered_name', 'trade_name', 'role', 'state', 'confidence_score', 'domain', 'remote_logo_url', 'country', 'business_type', 'confirmable', 'confirmable_reason'], 'properties': {'role': {'anyOf': [{'enum': ['primary', 'sibling'], 'type': 'string'}, {'type': 'null'}]}, 'state': {'enum': ['pending', 'confirmed', 'dismissed', 'snoozed'], 'type': 'string'}, 'domain': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "The company's domain, a logo source and a display fallback."}, 'country': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "The company's country, for a light detail panel."}, 'company_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'trade_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'confirmable': {'type': 'boolean', 'description': 'Whether well_create_company_workspace accepts this candidate now. False for a name-only detected candidate with no groundable identity, or one that has left the surfaced set.'}, 'candidate_id': {'type': 'string', 'description': "The candidate's id — pass to well_create_company_workspace to mint the company workspace from it."}, 'business_type': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "The company's legal form (SAS, Inc, GmbH), when known."}, 'registered_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'remote_logo_url': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': 'A resolved logo url when one is known; null otherwise.'}, 'confidence_score': {'type': 'number'}, 'confirmable_reason': {'anyOf': [{'enum': ['not_open', 'not_surfaceable', 'not_primary', 'already_confirmed', 'not_grounded'], 'type': 'string'}, {'type': 'null'}], 'description': 'Why confirmable is false, null when true. not_grounded: no registry or tax identifier to mint from; ask the user to search the registry and pick the verified entry. not_open: no longer the surfaced candidate; re-read the own-company list before acting. Others: not_primary, already_confirmed, not_surfaceable.'}}, 'additionalProperties': False}}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_get_schema

Get schema

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"]

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'root': {'type': 'string', 'description': 'Entity root to inspect. Omit to list every available root (call well_get_schema() with no argument first). Includes the accounting graph (ledger_accounts, journals, journal_entries) alongside companies, invoices, transactions, accounts, and more.'}, 'depth': {'type': 'number', 'default': 1, 'maximum': 3, 'minimum': 0, 'description': 'Relationship depth: 0=scalars only, 1=direct relations (default), 2=nested, 3=level-3 graph'}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Optional: this tool describes the token itself rather than one workspace's data, so omitting it returns the same answer."}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'root': {'type': 'string'}, 'error': {'type': 'string'}, 'roots': {'type': 'array', 'items': {'type': 'string'}}, 'total': {'type': 'number'}, 'fields': {'type': 'array', 'items': {'type': 'object', 'required': ['path', 'type'], 'properties': {'path': {'type': 'string'}, 'type': {'type': 'string'}, 'context': {'type': 'string'}, 'enrichment': {'type': 'string'}}, 'additionalProperties': False}}, 'success': {'type': 'boolean'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_get_session_digest

Get session digest

Get everything a returning person's first answer needs, in one call: what happened in the workspace since they last looked, where the workspace stands now, and the Well skills that can take it forward. When the person asks what happened since last time, asks to be caught up, or opens a session, do not call this first: load the `signing-back` skill with well_get_skill and follow it. That procedure greets, reads this digest, and proposes the next steps; calling this tool alone skips the greeting and the proposals. Call this tool directly only when a loaded Well skill says to, or when the person asks for the raw counts and nothing else. Returns `records` (one entry per record type with its created / updated / deleted counts and the connectors those creations came from), `errors` (the pipeline failures worth acting on), `skills_run` (the Well skills this person already ran recently, so you do not propose one they just finished), and `boundary` + `since_at` saying where the window starts. `is_first_session` true means there is no earlier moment to report from: greet the person and skip the recap. `truncated` true means the window stopped at 5000 events and the counts cover part of the tail only. Also returns `situation`, the state behind the recap, so no follow-up read is needed: `connectors` (the tools this workspace connected, each with its `connection_status` and `last_successful_sync_at`, beside `connected_count`; the size of Well's catalog is not carried, because it is never a figure to tell the person), `open_period` (the month Well opens the close on, with its `label`, `is_complete` and `selectable`), and `missing_invoices` (that month's `row_count` of counterparties with settled spend and no invoice, plus its `hints`). Each part is null when its read refused or had nothing to read. A null says the part is UNKNOWN: never report it as an empty connector list, a workspace with no open month, or a month owing nothing. And `skills`: the whole Well skill roster, the same entries well_search_skill returns, so a step a click names is loaded with well_get_skill rather than searched for again. `roster_readable` false says the roster could not be read at all, so `skills` is empty because nothing loaded: propose no next step in that turn, because every slug would be invented. And `suggested_steps`: the five next steps Well ranked for this workspace, each a `skill` from the roster and the `reason` it ranks there. The rubric runs on the server: open gaps first (no bank, a month owing invoices, no accounting tool, a stale sync), then the open month's close, then the analysis skills, and never a skill served in the last day. Hand these five to well_propose_next_steps in this order and rank nothing yourself. The sentence each one is offered as is yours to write, in the language the person is using, from that skill's own quoted utterances in `skills` and the figures above. When the list is empty, nothing was offerable: call no render tool and write no five of your own, say so in one line. Pass `mark: true` to advance this person's read cursor to the end of the window, so the next digest starts where this one ended. That cursor is shared with the app, so marking here also clears what the app shows as unread. Pass `mark: false` (or omit it) to inspect the digest without moving anything. The figures are computed by Well. State them as returned: do not re-count, round, or total them yourself. When the token authorizes one workspace, call this directly — no other tool call is needed first. When it authorizes several, this read will not guess which one you mean: pass `workspace_id` on the call.

Read only Idempotent

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'mark': {'type': 'boolean', 'description': "Advance this person's read cursor to the end of the window, so the next digest starts where this one ended. Pass true when you are about to report the digest to the person, false when you are only inspecting it."}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which."}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success', 'reason', 'boundary', 'since_at', 'since_at_label', 'time_zone', 'is_first_session', 'truncated', 'errors', 'records', 'skills_run', 'situation', 'skills', 'roster_readable', 'suggested_steps'], 'properties': {'error': {'type': 'string'}, 'errors': {'type': 'array', 'items': {'type': 'object', 'required': ['label', 'count'], 'properties': {'count': {'type': 'number'}, 'label': {'type': 'string'}}, 'additionalProperties': False}}, 'reason': {'anyOf': [{'enum': ['no_request_context', 'no_person', 'no_workspace', 'digest_unreadable'], 'type': 'string'}, {'type': 'null'}]}, 'skills': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'description'], 'properties': {'id': {'type': 'string'}, 'description': {'type': 'string'}}, 'additionalProperties': False}, 'description': 'The whole Well skill roster, the same entries well_search_skill returns. The step a click names is loaded from it with well_get_skill.'}, 'records': {'type': 'array', 'items': {'type': 'object', 'required': ['record_type', 'created', 'updated', 'deleted', 'sources'], 'properties': {'created': {'type': 'number'}, 'deleted': {'type': 'number'}, 'sources': {'type': 'array', 'items': {'type': 'object', 'required': ['provider_name', 'created'], 'properties': {'created': {'type': 'number'}, 'provider_name': {'type': 'string'}}, 'additionalProperties': False}}, 'updated': {'type': 'number'}, 'record_type': {'type': 'string'}}, 'additionalProperties': False}}, 'success': {'type': 'boolean'}, 'boundary': {'anyOf': [{'enum': ['watermark', 'previous_session', 'first_session'], 'type': 'string'}, {'type': 'null'}], 'description': "Where the window starts: the person's read cursor, their previous sign-in, or neither. Null on a refusal."}, 'since_at': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': 'The instant the window starts from, set only when a previous sign-in bounded it.'}, 'situation': {'type': 'object', 'required': ['connectors', 'open_period', 'missing_invoices'], 'properties': {'connectors': {'anyOf': [{'type': 'object', 'required': ['connected', 'connected_count'], 'properties': {'connected': {'type': 'array', 'items': {'type': 'object', 'required': ['name', 'kinds', 'is_connected', 'connection_status', 'last_successful_sync_at'], 'properties': {'name': {'type': 'string'}, 'kinds': {'type': 'array', 'items': {'enum': ['bank', 'accounting', 'invoicing'], 'type': 'string'}, 'description': 'The data domains this tool serves (bank, accounting, invoicing), as the connect card classifies it.'}, 'is_connected': {'type': 'boolean'}, 'connection_status': {'anyOf': [{'enum': ['enabled', 'processing', 'error', 'need_reconnect', 'to_configure', 'disabled'], 'type': 'string'}, {'type': 'null'}]}, 'last_successful_sync_at': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}, 'description': 'The tools this workspace has connected, read from its own connection rows. A row still waiting on its handshake, and one torn down, are not carried.'}, 'connected_count': {'type': 'number', 'description': 'Connected tools, which is the length of `connected`.'}}, 'additionalProperties': False}, {'type': 'null'}], 'description': 'Null when the connector read refused, which is not a claim that nothing is connected.'}, 'open_period': {'anyOf': [{'type': 'object', 'required': ['calendar_year', 'calendar_month', 'label', 'is_complete', 'selectable'], 'properties': {'label': {'type': 'string'}, 'selectable': {'type': 'boolean'}, 'is_complete': {'type': 'boolean'}, 'calendar_year': {'type': 'number'}, 'calendar_month': {'type': 'number'}}, 'additionalProperties': False}, {'type': 'null'}], 'description': 'The month Well opens the close on. Null when no month is ready, or when the period read refused.'}, 'missing_invoices': {'anyOf': [{'type': 'object', 'required': ['row_count', 'hints'], 'properties': {'hints': {'type': 'array', 'items': {'type': 'string'}}, 'row_count': {'type': 'number', 'description': 'Counterparties with settled spend and no invoice, in the open period.'}}, 'additionalProperties': False}, {'type': 'null'}], 'description': 'Null when no month was open to read, or when the read refused. Not a claim that nothing is missing.'}}, 'description': 'Where the workspace stands now: its connected tools, its open month, and what that month still owes.', 'additionalProperties': False}, 'time_zone': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "The IANA time zone the label was written in, from the workspace's settings."}, 'truncated': {'type': 'boolean', 'description': 'True when events sit past the read cap of 5000, so the counts cover part of the tail only.'}, 'skills_run': {'type': 'array', 'items': {'type': 'object', 'required': ['skill_slug', 'surface', 'count', 'last_run_at'], 'properties': {'count': {'type': 'number'}, 'surface': {'enum': ['web', 'mcp'], 'type': 'string'}, 'skill_slug': {'type': 'string'}, 'last_run_at': {'type': 'string'}}, 'additionalProperties': False}}, 'since_at_label': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': 'The same instant written in the workspace\'s own time zone, such as "Tuesday 8 September at 09:50", ready to quote in the greeting.'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'roster_readable': {'type': 'boolean', 'description': 'False when the roster could not be read at all, so `skills` is empty because nothing was readable rather than because the build ships no skill. Propose no next step on false: every slug would be invented and refused.'}, 'suggested_steps': {'type': 'array', 'items': {'type': 'object', 'required': ['skill', 'reason'], 'properties': {'skill': {'type': 'string', 'description': 'A skill id from `skills`.'}, 'reason': {'enum': ['open_gap', 'continuation', 'analysis'], 'type': 'string', 'description': "Why it ranks here: an open gap, the open month's continuation, or analysis."}}, 'additionalProperties': False}, 'description': "The five next steps Well ranked for this workspace, in card order, from its gaps, its open month and the skills already run. Hand these five to well_propose_next_steps in this order, never reordered or replaced. You write the sentence each one is offered as, in the language the person is using, from that skill's own quoted trigger utterances in `skills` and the figures this digest returned. Empty means nothing was offerable: draw no card and write no five of your own."}, 'is_first_session': {'type': 'boolean'}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_get_skill

Get skill

Get the Well procedure for a job, written by the Well team, and follow it exactly. Returns ONE markdown document: the instructions for the thing you are about to do. Its content is the instruction, not background reading — do what it says, in the order it says, and do not substitute your own plan for it. A document may tell you to run other Well skills. Load each one with this tool, by the id the document names, at the moment the document says to. Use well_search_skill first when you do not already hold the id. The catalog is fixed for the life of the server, so re-fetching a document you already hold buys nothing.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['skill'], 'properties': {'skill': {'type': 'string', 'pattern': '^[a-z0-9-]{1,64}$', 'description': 'The id of the skill to load, as well_search_skill lists it.'}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Optional: this tool describes the token itself rather than one workspace's data, so omitting it returns the same answer."}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success', 'reason', 'skill', 'bytes', 'document'], 'properties': {'bytes': {'type': 'number'}, 'error': {'type': 'string'}, 'skill': {'type': 'string'}, 'reason': {'anyOf': [{'enum': ['skill_unknown', 'catalog_unreadable', 'write_skill_in_app'], 'type': 'string'}, {'type': 'null'}]}, 'success': {'type': 'boolean'}, 'document': {'type': 'string'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_get_statement_import_result

Get statement import result

Read the outcome of a bank-statement upload started with well_create_statement_upload, by the document_id that tool returned. well_create_statement_upload already renders a card from its own result — this tool does not create or redraw it. Call it once, shortly after the client has uploaded the file bytes, to learn what happened. The card polls this import result itself until it settles, so call this tool again only if the user asks. - status "not_found_yet": the upload has not landed yet — a NORMAL result right after minting the slot, not an error. Poll again once the file has been uploaded. - status "processing": the file is uploaded and the statement is still being extracted / promoted. - status "imported" | "needs_account" | "duplicate" | "skipped" | "failed": the terminal outcome. On "imported", matched_count / review_count / minted_count / already_present_count report the promotion's own snapshot counts, taken once at import time and covering every promotable line of the file disjointly; null on any of them means the row predates count tracking — treat as unknown, never as 0. `records` lists the minted transactions only — matched or ambiguous lines link an existing transaction and are excluded; `graph` is the frozen record graph for the same snapshot; `records_url` opens the workspace's transactions table. This tool reads only — it changes nothing.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['document_id'], 'properties': {'document_id': {'type': 'string', 'description': 'The document_id well_create_statement_upload returned — pre-allocated at mint, before the upload lands.'}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which."}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'hint': {'type': 'string'}, 'error': {'type': 'string'}, 'graph': {'type': 'object', 'required': ['graph', 'category', 'contributingFileIds', 'silentFileIds'], 'properties': {'graph': {'type': 'object', 'required': ['nodes', 'edges', 'ownCompanyId'], 'properties': {'edges': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'source', 'target', 'kind'], 'properties': {'id': {'type': 'string'}, 'kind': {'enum': ['company_person', 'invoice_issuer', 'invoice_receiver', 'invoice_transaction', 'invoice_document', 'transaction_document', 'account_transaction', 'journal_entry_transaction', 'journal_entry_ledger_account', 'business_relation', 'workspace_connector_link', 'invoice_payment_means', 'transaction_payment_means', 'task_invoice', 'journal_journal_entry', 'provider_for', 'workspace_membership', 'company_note', 'person_note', 'note_note', 'same_entity'], 'type': 'string'}, 'source': {'type': 'string'}, 'target': {'type': 'string'}}, 'additionalProperties': False}}, 'nodes': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'type', 'label'], 'properties': {'id': {'type': 'string'}, 'type': {'enum': ['company', 'account', 'person', 'invoice', 'transaction', 'document', 'ledger_account', 'journal_entry', 'workspace_connector', 'payment_means', 'card', 'check', 'task', 'media', 'journal', 'blueprint_run', 'chat_conversation', 'connector', 'membership', 'memory', 'custom_column', 'field_rule', 'provider', 'note'], 'type': 'string'}, 'label': {'type': 'string'}}, 'additionalProperties': {}}}, 'ownCompanyId': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}, 'category': {'anyOf': [{'enum': ['companies', 'banks', 'people', 'invoices', 'transactions', 'documents'], 'type': 'string'}, {'type': 'null'}]}, 'silentFileIds': {'type': 'array', 'items': {'type': 'string'}}, 'contributingFileIds': {'type': 'array', 'items': {'type': 'string'}}}, 'description': 'The frozen record graph for this import, taken from the same snapshot as `records`. Never present on "processing" or "not_found_yet". Like `records`, its counterparty fields are null (frozen before resolution runs) — see `records_url` for the live values.', 'additionalProperties': False}, 'phase': {'anyOf': [{'enum': ['queued', 'extracting', 'categorized', 'importing'], 'type': 'string'}, {'type': 'null'}]}, 'reason': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'status': {'enum': ['not_found_yet', 'processing', 'needs_account', 'imported', 'duplicate', 'skipped', 'failed'], 'type': 'string'}, 'records': {'type': 'array', 'items': {'type': 'object', 'required': ['root', 'id', 'date', 'label', 'amount', 'currency', 'counterparty', 'receiver', 'category', 'primaryBadge', 'secondaryBadge', 'openingBooked', 'closingBooked', 'balanceAtFrom', 'domain'], 'properties': {'id': {'type': 'string'}, 'date': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'root': {'enum': ['companies', 'people', 'invoices', 'documents', 'transactions', 'accounts', 'connectors', 'workspace_connectors', 'ledger_accounts', 'journals', 'journal_entries', 'tax_rates', 'invoice_transactions', 'memberships', 'payment_means', 'media', 'emails', 'phones', 'web_links', 'locations', 'categories', 'invoice_items', 'account_balances', 'exchange_rates', 'cards', 'checks', 'invoice_payment_means', 'workspaces', 'blueprint_runs', 'chat_conversations', 'tasks', 'billing_events'], 'type': 'string'}, 'label': {'type': 'string'}, 'amount': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'domain': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'category': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'currency': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'receiver': {'anyOf': [{'type': 'object', 'required': ['name', 'logo_url'], 'properties': {'name': {'type': 'string'}, 'logo_url': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}, {'type': 'null'}]}, 'counterparty': {'anyOf': [{'type': 'object', 'required': ['name', 'logo_url'], 'properties': {'name': {'type': 'string'}, 'logo_url': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}, {'type': 'null'}]}, 'primaryBadge': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'balanceAtFrom': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'closingBooked': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'openingBooked': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'secondaryBadge': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}, 'description': 'Transactions this import minted as new rows — matched or ambiguous lines link an existing transaction and are excluded. Present only on a terminal "imported" result that carries a snapshot. The snapshot freezes at mint time, so `counterparty` is always null here — resolution runs asynchronously after import; open `records_url` for the live resolved value.'}, 'success': {'type': 'boolean'}, 'document_id': {'type': 'string'}, 'imported_at': {'type': 'string'}, 'records_url': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "Login-gated deep link to the workspace's transactions table — opened on the first minted record when `records` is non-empty, otherwise the plain table."}, 'minted_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Lines minted as new transactions. Absent means the row predates count tracking — treat as unknown, never as 0.'}, 'review_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Lines skipped as an ambiguous cross-connector match, pending review. Absent means the row predates count tracking — treat as unknown, never as 0.'}, 'matched_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Lines linked to an existing cross-connector transaction. Absent means the row predates count tracking — treat as unknown, never as 0.'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'already_present_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': "Lines an earlier import already carried — a partial-overlap re-export mints only the new lines, so the four counts cover the file's promotable lines. Absent means the row predates count tracking — treat as unknown, never as 0."}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}, 'counterparties_pending': {'type': 'boolean', 'description': 'Whether any minted transaction still awaits its counterparty. True right after import while the from/to parties resolve in the background; absent when the result carries no minted transactions.'}, 'statement_extraction_id': {'type': 'string'}}, 'additionalProperties': False}

well_get_worklist_status

Get worklist status

Ask whether a repair gate is still OPEN, without drawing its card. Call this BEFORE the worklist read whenever you are checking rather than repairing — the first pass of a gate, and every re-check after the reader has cleared one. `open: false` means the gate is settled: carry on, and call nothing else. **Only call the worklist read when this says `open: true`.** Those reads draw a card on every call, empty included, so reaching for one to find out whether there is anything to do puts a picker with no rows and a dead button in front of the reader. The tool that draws each card comes back as `card_tool`. WORKLISTS, and the scope each one needs: - `accounts_needing_company` — the accounts with no company attached, or whose ownership is still unknown. No scope. - `uncategorized_window` — the transactions in a window carrying no category. Needs `from` (inclusive) and `to` (EXCLUSIVE), both `YYYY-MM-DD`. - `unposted_transactions` — a period's categorized rows still missing the ledger account they would post to. Needs `fiscal_year` and `fiscal_period`. - `invoice_sources_for_pick` — how many of the vendors the user picked on the missing-invoices card carry a connector that can bring an invoice in. No scope: the pick is on this session's own lane. Ask it BEFORE any `well_list_connectors({ from_selection: true })` call, and make that call only when this answers above zero — a pick with no invoice source behind it draws a picker with no rows and a dead button. - `counterparties_to_categorize` — the counterparties whose invoices the named months are still missing and that carry no industry category. Needs `periods`, the same `[{ calendar_year, calendar_month }]` list the card takes. A scope field the named worklist needs is REQUIRED. Omit one and this refuses: a gate reported clear over the wrong window cannot be told from one that is genuinely clear, and the figure behind it would be computed on that. **`success: false` means the gate is UNKNOWN, not clear.** `open` is ABSENT on that path, so a failed read can never be mistaken for a settled worklist. Retry once; on a second failure say the gate could not be read and stop, rather than computing a figure on evidence you never obtained. Most worklists report no COUNT. One row answers "is it open", and the count of what is left comes from the worklist read itself — which you are about to call anyway when the gate is open. Two kinds are the exception and carry `count`. `invoice_sources_for_pick` reads its whole set by id in one go, never paged, so the number comes free. `counterparties_to_categorize` reads the whole month population rather than one row, so the number is already in hand, and it is the same number the card reports as `uncategorized_count`. COST: `counterparties_to_categorize` reads each named month's spend — the same reads its card makes, and a scope with work left in it pays for them TWICE, once here and once when the card draws. A clean scope pays once and skips the card entirely, which is what the check buys. Probe the months the user actually named, not a whole year "to be safe". When the token authorizes one workspace, call this directly — no other tool call is needed first. When it authorizes several, this read will not guess which one you mean: pass `workspace_id` on the call. That holds for every gate but two. `invoice_sources_for_pick` and `counterparties_to_categorize` follow their cards instead: `well_list_connectors` and `well_list_counterparties` both answer from the token's primary workspace when you name none, so those gates answer from the same one. A probe that refused where its card answers would be describing a different workspace from the card it stands in for. The result names the workspace that answered.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['worklist'], 'properties': {'to': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$', 'description': "`uncategorized_window` only: the day AFTER the window's last, exclusive."}, 'from': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$', 'description': "`uncategorized_window` only: the window's first day, inclusive."}, 'periods': {'type': 'array', 'items': {'type': 'object', 'required': ['calendar_year', 'calendar_month'], 'properties': {'calendar_year': {'type': 'integer', 'maximum': 2100, 'minimum': 2000, 'description': 'Calendar year, e.g. 2026.'}, 'calendar_month': {'type': 'integer', 'maximum': 12, 'minimum': 1, 'description': 'Calendar month, 1 = January … 12 = December.'}}, 'additionalProperties': False}, 'maxItems': 12, 'minItems': 1, 'description': '`counterparties_to_categorize` only: the calendar months to check, the same list the card takes. Every month must have ended.'}, 'worklist': {'enum': ['accounts_needing_company', 'uncategorized_window', 'unposted_transactions', 'invoice_sources_for_pick', 'counterparties_to_categorize'], 'type': 'string', 'description': "Which repair gate to check. Each one names its own required scope in this tool's description."}, 'fiscal_year': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': "`unposted_transactions` only: the period's fiscal year."}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which."}, 'fiscal_period': {'type': 'integer', 'maximum': 13, 'minimum': 1, 'description': '`unposted_transactions` only: the fiscal period, 1-12 for a month; 13 is the adjustment period and resolves to no rows.'}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['worklist', 'card_tool', 'success'], 'properties': {'open': {'type': 'boolean', 'description': 'Whether the worklist still holds a row. Absent when `success` is false — an unknown gate, not a clear one.'}, 'count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': "How many rows the gate still holds. Carried only by the kinds whose read counts the whole set (`invoice_sources_for_pick`, and `counterparties_to_categorize` where it equals the card's `uncategorized_count`); absent on the kinds answered one row at a time, and absent whenever `success` is false."}, 'error': {'type': 'string'}, 'success': {'type': 'boolean'}, 'worklist': {'type': 'string', 'description': 'The gate that was checked, echoed back.'}, 'card_tool': {'type': 'string', 'description': "The tool that draws this worklist's repair card. Call it only when `open` is true."}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_invite_members

Invite members

Invite one or more teammates into a workspace, or into a workspace group. Use it after well_list_member_candidates, on the people the user chose. Pass `invites` — 1 to 20 `{ email, role }`, role `admin` or `member` — and a `target`: `{ kind: "workspace" }` for this workspace, or `{ kind: "group", group_id }` for a group you belong to. Only a workspace owner or admin may invite; a caller without that role is refused. Returns one `results` entry per invite: `status` `sent` (a new invitation), `reissued` (an already-pending address got a fresh link), or `refused` — with `refusal_reason` naming why, ALREADY_WORKSPACE_MEMBER when the address already has access and INSUFFICIENT_PERMISSIONS when the caller may not invite. `invitation_email_sent` is false when the invite persisted but the email did not leave, so offer a resend. Each successful result carries `person_id` for the invited address. Never invite an address already active in the workspace. Pass `notify: false` (workspace target only) to create or reissue the pending membership WITHOUT emailing — for the assign-then-invite flow where an owner is assigned by a typed email now and the invitation is sent later from the invite card. Use the returned `person_id` to assign that person as an owner without a second lookup.

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['invites', 'target'], 'properties': {'notify': {'type': 'boolean', 'description': 'Send the invitation email now. Defaults to true. Pass false to create or reissue the pending membership WITHOUT emailing, when a later explicit step sends it — e.g. assigning an owner by a typed email, then sending the invite from the invite card. Applies to a workspace target only; a group invite always notifies.'}, 'target': {'oneOf': [{'type': 'object', 'required': ['kind'], 'properties': {'kind': {'type': 'string', 'const': 'workspace'}}, 'additionalProperties': False}, {'type': 'object', 'required': ['kind', 'group_id'], 'properties': {'kind': {'type': 'string', 'const': 'group'}, 'group_id': {'type': 'string', '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)$'}}, 'description': 'Invite into a workspace group the caller belongs to.', 'additionalProperties': False}], 'description': 'Where the invites land: this workspace, or a workspace group.'}, 'invites': {'type': 'array', 'items': {'type': 'object', 'required': ['email', 'role'], 'properties': {'role': {'enum': ['admin', 'member'], 'type': 'string', 'description': 'The role to grant on acceptance: admin or member.'}, 'email': {'type': 'string', 'format': 'email', 'pattern': "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", 'description': "The teammate's email address."}}, 'additionalProperties': False}, 'maxItems': 20, 'minItems': 1, 'description': 'The people to invite, 1 to 20 per call.'}, 'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.'}, 'conversation_id': {'type': 'string', '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.'}, 'idempotency_key': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['results', 'success'], 'properties': {'error': {'type': 'string'}, 'results': {'type': 'array', 'items': {'type': 'object', 'required': ['email', 'status', 'invitation_email_sent'], 'properties': {'email': {'type': 'string'}, 'status': {'enum': ['sent', 'reissued', 'refused'], 'type': 'string'}, 'person_id': {'type': 'string', 'description': "The invitee's person id on a successful workspace invite (sent or reissued). Use it to assign the person as an owner right after inviting, with no second lookup. Absent on a refusal and on a group invite."}, 'refusal_reason': {'type': 'string', 'description': 'Present only when status is refused. Named reasons include ALREADY_WORKSPACE_MEMBER (the address already has access) and INSUFFICIENT_PERMISSIONS (the caller is not an owner or admin).'}, 'invitation_email_sent': {'type': 'boolean', 'description': 'False when the invite persisted but the email did not send — offer a resend.'}}, 'additionalProperties': False}, 'description': 'One result per invite, in the order they were sent.'}, 'success': {'type': 'boolean'}, 'workspace_id': {'type': 'string'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_invoke_connector_tool

Invoke connector tool

Run one tool on a connected provider's own MCP server, on behalf of this workspace's connection: an action the user asked to take there (create a record in Attio), or a read of content Well does not sync (a page in a docs tool, a note in a CRM, a file the user pasted a link to). It is NOT a way to read financial data: Well already syncs invoices, transactions, accounts and the accounting graph from every connected provider — read those with well_query_records instead of calling a provider's own list/read tools. WORKFLOW: 1. well_list_connectors() → pick the ENABLED provider (connection_status: "enabled") and read its workspace_connector_id directly off the row. A workspace_connector_id the user pasted is fine to use as-is: it is resolved inside this workspace, and an id that does not belong here fails server-side. 2. well_list_connector_tools({ workspace_connector_id }) → the live tool names + input schemas that connection actually exposes right now. 3. well_invoke_connector_tool({ workspace_connector_id, tool: "<one of the names from step 2>", 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.

Destructive Open world

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['workspace_connector_id', 'tool'], 'properties': {'args': {'type': 'object', 'description': 'Arguments object passed straight to the provider tool. Omit if the tool takes none.', 'propertyNames': {'type': 'string'}, 'additionalProperties': {}}, 'tool': {'type': 'string', 'minLength': 1, 'description': "The provider tool name to run (one of the connector's available_tools)."}, 'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.'}, 'conversation_id': {'type': 'string', '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.'}, 'idempotency_key': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.'}, 'workspace_connector_id': {'type': 'string', 'minLength': 1, 'description': "The connected provider's workspace_connector_id (from well_list_connectors)."}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'tool': {'type': 'string'}, 'error': {'type': 'string'}, 'result': {}, 'success': {'type': 'boolean'}, 'error_code': {'type': 'string'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_list_account_balances

List account balances

List every account on the workspace with its stored balance. Rows only — this tool holds no definition of cash, and returns no figure the app renders. Use it when you are computing a cash figure whose RULES you are stating yourself: which accounts belong to the business, which account types count as cash, which stored field is "the balance", what each currency converts at. The server derives no cash position of its own from this call, so a cash figure starts here: state the rules, keep exactly the rows they admit, then put the result on a card with `well_render_cash_position` — or, when the answer is cash month by month rather than one total, with `well_render_cash_forecast`. **It applies no scope.** Every active account comes back, including ones you will almost certainly exclude. `ownership` is `workspace`, `counterparty` or `unknown`, and it decides membership together with `company_id`: - `workspace` — the business's own, EXCEPT when `own_company_id` is set AND the row names a different company. A row with no `company_id` is trusted, because a connector tags a row before any holder is known; so is a row naming a company while `own_company_id` is still `null`, because nothing has disproved the pairing yet. Only a tag contradicting a resolved anchor is stale, and counting that one widens the owned scope and overstates the figure. - `counterparty` — not the business's, unconditionally. - `unknown` — unsettled, and settled ONLY by the anchor: own when `company_id` equals `own_company_id`, a counterparty's when it names a different one. `own_company_id` is `null` when the workspace has not set one. Nothing is settled against it then — no `unknown` row, and no `workspace` row's company pairing either — so say so rather than counting or dropping on a guess. This is the same three-way rule the app's own canvas account scope applies, and a figure that departs from it disagrees with the number the product shows. **It applies no type filter.** `account_type` is one of deposit, credit, loan, investment, payroll, other. A credit or loan account is a liability, so its balance normally nets out of cash rather than adding to it — but that is your decision to state, not a fact about the row, and the sign stored is the sign the provider sent. **It chooses no amount.** `closing_booked` is SETTLED cash; `closing_value` includes pending and uncleared movements. The two differ by every initiated-but-unsettled payment, so which one you total is the single most consequential choice a cash figure makes: state it. `opening_booked` is the fallback for a freshly-opened balance with no settled activity yet. Any of them is `null` when the stored value was absent or not a finite number, which is not a zero balance. **It converts nothing.** Each reading carries its own `currency`, which can differ from the account's own `account_currency`. Convert per row at a rate you can state, then total — a sum across currencies is denominated in nothing and no field here would say it happened. **It lists each copy of an account.** One physical account can arrive once per connector that syncs it. `duplicate_of_account_id` names the account a row is a second copy of, and is `null` on every other row. Leave a marked row out of every total and every count: the balance that counts is the named account's, which is the one the app's own figure reads, and the transactions of both copies are counted once. Total both copies and the figure holds that money twice. When the named account has no readable balance, report it as having none rather than taking the copy's reading in its place, or the figure departs from the app's. Marking follows the ownership rule above: only the business's own accounts are marked, and an `unknown` row only once `own_company_id` settles it. `balance` is `null` when no row was selected for that account. Two different situations produce it and they must not be reported the same way: `verification_rejected: true` means the newest balance failed verification and the bounded walk back found no verified one, so the data is repudiated; `false` means the account simply has no history yet. `months_back` adds `month_ends` to every row: one reading per complete month end, oldest first, keyed `YYYY-MM`, ending on the last COMPLETE month. This series is where a cash forecast starts — "what will our cash look like", "project our cash forward", "when do we hit zero" — and it is the settled half of `well_render_cash_forecast`; the projected half is that series' last settled month minus the burn you measure with `well_sum_transactions`. A `null` reading is a month no stored row covered — not a zero balance, so never plot it as one and never interpolate between two real points. Omit `months_back` for the current reading alone; the series is a second query and is not free. `partial: true` means the read was cut short BEFORE RETURNING ANYTHING, so it always arrives with an empty `rows` — it is a fact about the call, never a coverage figure over rows you received. Nothing is known about what is there, so derive no figure from it: say the read was cut short and offer to try again. `unreadable_rows` is the separate case and the only one that continues: the read finished, and that many rows carried a stored balance that could not be parsed. They hold a `null` balance, sit in no figure, and make any total a floor, by up to their count: the count covers every row, whatever its owner or type. When the token authorizes one workspace, call this directly — no other tool call is needed first. When it authorizes several, this read will not guess which one you mean: pass `workspace_id` on the call.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'months_back': {'type': 'integer', 'maximum': 24, 'minimum': 1, 'description': 'How many complete month ends to carry per account, oldest first. Omit for the current reading alone.'}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which."}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['rows', 'base_currency', 'own_company_id', 'partial', 'unreadable_rows', 'success'], 'properties': {'rows': {'type': 'array', 'items': {'type': 'object', 'required': ['account_id', 'account_name', 'account_type', 'account_subtype', 'ownership', 'company_id', 'company_name', 'account_currency', 'institution_name', 'masked_account_number', 'duplicate_of_account_id', 'balance', 'verification_rejected'], 'properties': {'balance': {'anyOf': [{'type': 'object', 'required': ['closing_booked', 'opening_booked', 'closing_value', 'opening_value', 'currency', 'balance_at_from', 'balance_at_to', 'is_reconstructed'], 'properties': {'currency': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'balance_at_to': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'closing_value': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'opening_value': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'closing_booked': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'opening_booked': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'balance_at_from': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'is_reconstructed': {'type': 'boolean'}}, 'additionalProperties': False}, {'type': 'null'}]}, 'ownership': {'type': 'string'}, 'account_id': {'type': 'string'}, 'company_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'month_ends': {'type': 'array', 'items': {'type': 'object', 'required': ['month', 'reading'], 'properties': {'month': {'type': 'string'}, 'reading': {'anyOf': [{'type': 'object', 'required': ['closing_booked', 'opening_booked', 'closing_value', 'opening_value', 'currency', 'balance_at_from', 'balance_at_to', 'is_reconstructed'], 'properties': {'currency': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'balance_at_to': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'closing_value': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'opening_value': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'closing_booked': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'opening_booked': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'balance_at_from': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'is_reconstructed': {'type': 'boolean'}}, 'additionalProperties': False}, {'type': 'null'}]}}, 'additionalProperties': False}}, 'account_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'account_type': {'type': 'string'}, 'company_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'account_subtype': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'account_currency': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'institution_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'masked_account_number': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'verification_rejected': {'type': 'boolean'}, 'duplicate_of_account_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}}, 'error': {'type': 'string'}, 'partial': {'type': 'boolean'}, 'success': {'type': 'boolean'}, 'base_currency': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'own_company_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'unreadable_rows': {'type': 'number'}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_list_accounts_needing_company

List accounts needing a company

List the workspace's accounts that cannot yet be placed on either side of a transfer, so a figure that depends on account ownership can say exactly what is missing before it is computed. Two states, ONE worklist, because they answer one question — whose account is this: - No company attached. Nothing can place the account on either side of a transfer. - `ownership: "unknown"`. The account has a company, and whether the workspace owns it is unanswered. The second is not the lesser case. An account left `unknown` sits outside the internal-transfer rule exactly as an unattached one does. **This is a gate on a FIGURE, not a tidiness list.** `well_sum_transactions` with `exclude_internal_transfers` keeps the rows with exactly one leg on an account the workspace OWNS, and drops the two-leg ones. So an account's ownership decides whether its movements count as money leaving the business. An account wrongly marked as the workspace's own removes real spend from the figure, quietly, with no error anywhere. **Do not propose an owner of your own.** You cannot read one off an account's name, its bank, or the company that appears most often beside it — a name-shaped match proposes the company minted FROM that name, and the bank that issues an account is not its owner. Where the system HAS a grounded proposal it rides on the row as `company_suggestion`, and the card is where a reader accepts it. `unknown` is a truthful state and a wrong classification is not. Each row carries `account_id` (pass it to `well_assign_account`), `account_name`, `iban`, `currency`, the `company_id` and `company_name` already attached when the gap is the ownership rather than the link, and `ownership`. `own_company_id` names the company that IS the workspace. It is what settles ownership without guessing: an account attached to that company is the business's own, and one attached to any other company belongs to a counterparty. When it is null the workspace has set no anchor, so nothing here settles ownership and the account stays `unknown` until a reader says otherwise. The companies a reader can pick ride alongside the rows, capped. When the workspace holds more than the cap, narrow them with `company_search` rather than assuming the card carries every company. A row whose ownership is already `workspace` carries `company_suggestion`: the company that IS the workspace, which is what such an account belongs to by definition. The field is ABSENT on a `counterparty` or still-`unknown` row, and on a workspace with no anchor set — absent means nothing grounded a guess, never that the row was checked and has no owner. It is a proposal for a reader to accept, not a decision: ownership decides whether an account sits in the workspace's own set at all, so never write it without the reader choosing it. `truncated: true` means the page filled and more accounts exist, so report the count as a floor rather than as the total. **`success: false` means the worklist is UNKNOWN, not empty.** The read failed, so no count exists. An empty `records` on a failed read is not "every account is settled" — treating it that way lets a figure be computed on evidence it never obtained. When the user asks to see, list or fix these rows, call this tool directly: its card is the answer. ⚠️ **This tool draws its card on EVERY call, the empty one included.** So when nobody asked for the list and you only need to CHECK whether anything is left (the first pass of a gate, or a re-check after a repair), call `well_get_worklist_status({ worklist: "accounts_needing_company" })` first. It draws nothing. Call this tool after it only when it answers `open: true`. When the token authorizes one workspace, call this directly — no other tool call is needed first. When it authorizes several, this read will not guess which one you mean: pass `workspace_id` on the call.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'limit': {'type': 'integer', 'maximum': 200, 'minimum': 1, 'description': 'Max accounts to return (default 200).'}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which."}, 'company_search': {'type': 'string', 'maxLength': 200, 'minLength': 1, 'description': 'Narrows the companies offered on the card by name, server-side. Use it when the workspace holds more companies than one page and the one the user means is not on it.'}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['records', 'success'], 'properties': {'error': {'type': 'string'}, 'records': {'type': 'array', 'items': {'type': 'object', 'propertyNames': {'type': 'string'}, 'additionalProperties': {}}}, 'success': {'type': 'boolean'}, 'returned': {'type': 'number'}, 'truncated': {'type': 'boolean'}, 'own_company_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': 'The company that IS the workspace; null when no anchor is set.'}, 'company_catalog': {'type': 'object', 'required': ['returned', 'total', 'truncated', 'failed'], 'properties': {'total': {'type': 'number'}, 'failed': {'type': 'boolean'}, 'returned': {'type': 'number'}, 'truncated': {'type': 'boolean'}}, 'description': 'How many companies the card was given against how many the workspace holds. `truncated: true` means the one the user means may not be on the card — narrow with `company_search`.', 'additionalProperties': False}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_list_burn_exemptions

List burn exemptions

List the categories a reader can exempt from burn over one window, each with the spend exempting it would remove. This is what the exemption card offers; it measures nothing the sum did not already measure. Each entry in `groups` is one category's OUTFLOW in the window: `category_key` (the id an exemption is matched on), `label` (the category as the product writes it), `amount` (a magnitude, never signed) and `count` (the rows behind it). Sorted by amount descending, so the biggest decision reads first. A category with no outflow in the window is NOT listed — exempting it would remove nothing, so it is not a choice. `total` is the sum of `groups[].amount` and nothing else. `unclassified_amount` and `unclassified_count` are the outflow this list cannot offer as a choice: rows carrying no category, which no exemption ever matches, and rows whose category is outside the shared vocabulary, which this read cannot name for a reader. The two are reported together because both leave the reader's choices unable to touch that money — not because the same thing is true of them downstream. `total + unclassified_amount` is the window's whole outflow, so a reader can see what the choices do not cover. State the unclassified figure whenever it is not zero rather than presenting `total` as the whole window. Pass the `convention` you elected for the burn figure itself. The list and the figure have to sit on one election, and this read deliberately does not make a second one. `partial: true` means the underlying sum measured nothing, so `groups` is empty and nothing is known about the window's spend. Say so and offer to try again, rather than presenting an empty list as a decision. `unreadable_rows` counts rows whose amount could not be read at all; they are in no figure here. `from` is inclusive and `to` is EXCLUSIVE, so a window of whole months passes the first instant of the month after the last one you want. `window` echoes both back exactly as you sent them. Internal transfers are already out. This read keeps only the rows with exactly one leg on an account the workspace owns — the same rule the burn applies — so a movement between the workspace's own accounts never appears here. `currency` is the one currency every row in the window shares. A window holding more than one, or holding a row that carries none, is REFUSED with `success: false` and an `error` saying which: adding two currencies gives a number denominated in nothing, and no field on this result could say it happened. `currency` is the EMPTY STRING only when the window held no row at all, and then `groups` is empty and both totals are zero. The direction convention is elected ONCE over the whole window, never per category. A window whose rows are overwhelmingly negative stores an outflow as a negative amount, and these figures are that branch. A window that stores outflows as positive magnitudes keeps the direction in a field this grouping does not read, and a window that pools both kinds of feed has no single outflow at all — both are REFUSED with an `error` naming the counts behind the decision, rather than reported as spend. Take the reader's answer from the card, record it with `well_switch_workspace` as `exempt_categories`, and read it back with `well_wait_for_selection` (kind "exemptions"). The record belongs to this conversation. Another conversation does not read it. Then pass the same keys to `well_sum_transactions` as `exempt_categories` to compute the burn without them, and name the exemptions beside the figure so it can be read back. When the token authorizes one workspace, call this directly — no other tool call is needed first. When it authorizes several, this read will not guess which one you mean: pass `workspace_id` on the call.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['from', 'to', 'convention'], 'properties': {'to': {'type': 'string', 'description': 'EXCLUSIVE end of the window, ISO-8601 — the first instant after the last month you want.'}, 'from': {'type': 'string', 'description': 'Inclusive start of the window, ISO-8601 (e.g. 2026-06-01).'}, 'convention': {'enum': ['signed', 'magnitude'], 'type': 'string', 'description': 'Which sign means money leaving, as YOU elected it for the figure these exemptions apply to — the same election `well_render_burn` takes. This read does not elect its own: a share of positive rows cannot tell a business with revenue apart from two feeds pooled together, and guessing would either refuse ordinary workspaces or total two conventions as one. Pass "signed" when the window\'s rows are mostly negative for spend, "magnitude" when the feed stores outflows as positive numbers. A "magnitude" window is refused, because direction then lives in a field this read does not group on.'}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which."}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success', 'groups', 'currency', 'total', 'unclassified_amount', 'unclassified_count', 'partial', 'unreadable_rows', 'window'], 'properties': {'error': {'type': 'string'}, 'total': {'type': 'number', 'description': 'The sum of groups[].amount, and nothing else.'}, 'groups': {'type': 'array', 'items': {'type': 'object', 'required': ['category_key', 'label', 'amount', 'count'], 'properties': {'count': {'type': 'number'}, 'label': {'type': 'string'}, 'amount': {'type': 'number', 'description': "This category's outflow in the window, as a magnitude."}, 'category_key': {'type': 'string', 'description': 'The value an exemption is matched on, exactly as the rows store it.'}}, 'additionalProperties': False}}, 'window': {'type': 'object', 'required': ['from', 'to'], 'properties': {'to': {'type': 'string'}, 'from': {'type': 'string'}}, 'additionalProperties': False}, 'partial': {'type': 'boolean', 'description': 'True when the sum behind this card measured nothing. `groups` is then empty, so there is no list to choose from: say so and offer to try again.'}, 'success': {'type': 'boolean'}, 'currency': {'type': 'string', 'description': 'The one currency every row shares; empty only when the window held no row.'}, 'next_step': {'type': 'string', 'description': 'What to do with the card this result renders. Added by the dispatcher when the card asks for a click.'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'unreadable_rows': {'type': 'number', 'description': 'Rows in the window whose amount could not be read. They are in no figure here, including the unclassified one.'}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'unclassified_count': {'type': 'number'}, 'unclassified_amount': {'type': 'number', 'description': 'Outflow this list cannot offer as a choice: rows with no category, which no exemption ever matches, and rows whose category is outside the shared vocabulary, which cannot be named here.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_list_cash_scope

List cash scope by account type

List the account types a reader can count as cash, each with what it holds. This is what the cash-scope card offers; it measures nothing `well_list_account_balances` did not already read. Each entry in `groups` is one account type: `account_type`, `account_count`, and `subtotals` — one native amount per currency, never converted and never blended. Sorted with the largest holdings first, so the biggest decision reads first. A type with no accounts is NOT listed: counting it would change nothing, so it is not a choice. **Only accounts the workspace owns are folded here.** Ownership is settled by a fact about the account, not by a preference, so it is never offered as a choice on this card. `excluded_not_owned` counts what that removed, and `unsettled_ownership` counts accounts whose owner is unanswered — those are NOT in any group, and a non-zero count means the reader has a repair to do before any total is trustworthy. Say it rather than presenting the groups as the whole picture. `unreadable_balances` counts owned accounts whose stored balance could not be read at all; `unreadable_currency` counts those carrying an amount with no currency code anywhere. Both are in no subtotal, so state them beside any figure rather than presenting one that silently skipped them — and keep them apart, because they are different repairs: a balance that did not arrive against a row that arrived incomplete. `folded_duplicates` counts rows left out because they are a second copy of an account already listed, synced once per connector. They are in no group and no count, since the account they copy is counted once. `partial: true` means the underlying read was cut short before it returned anything, so `groups` is empty and nothing is known about what the workspace holds. Say the read was cut short and offer to try again, rather than presenting an empty list as a decision. The card records the reader's answer in this session, so wait for it: call `well_wait_for_selection({ kind: "cash_scope" })` in the SAME turn, and read `selection.counted_account_types`. An EMPTY array there is the answer "nothing is cash" — a resolution that ends the run, never a zero total. Do not settle the scope yourself: on a workspace holding more than one type that is the figure decided on the reader's behalf. A card listing no type at all asks nothing and carries no wait. Once the answer is in, YOU apply it when you total the balances, then call `well_render_cash_position` with the types you counted in `scope.account_types`. When the token authorizes one workspace, call this directly — no other tool call is needed first. When it authorizes several, this read will not guess which one you mean: pass `workspace_id` on the call.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which."}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['groups', 'excluded_not_owned', 'unsettled_ownership', 'unreadable_balances', 'unreadable_currency', 'folded_duplicates', 'partial', 'success'], 'properties': {'error': {'type': 'string'}, 'groups': {'type': 'array', 'items': {'type': 'object', 'required': ['account_type', 'account_count', 'subtotals'], 'properties': {'subtotals': {'type': 'array', 'items': {'type': 'object', 'required': ['currency', 'amount'], 'properties': {'amount': {'type': 'number'}, 'currency': {'type': 'string'}}, 'additionalProperties': False}}, 'account_type': {'type': 'string'}, 'account_count': {'type': 'number'}}, 'additionalProperties': False}}, 'partial': {'type': 'boolean'}, 'success': {'type': 'boolean'}, 'next_step': {'type': 'string', 'description': 'What to do with the card this result renders. Added by the dispatcher when the card asks for a click.'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'folded_duplicates': {'type': 'number'}, 'excluded_not_owned': {'type': 'number'}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'unreadable_balances': {'type': 'number'}, 'unreadable_currency': {'type': 'number'}, 'unsettled_ownership': {'type': 'number'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_list_connectors

List connectors

List the connectors a workspace can install AND everything it has already connected, each with a one-click install deep link. The result DRAWS THE CONNECT CARD the user clicks in. ONE tool answers both halves of the connect question — "what can I connect to Well?" and "what is connected, still syncing, or broken?" — because every existing connection is overlaid onto its catalog row. Do NOT read workspace_connectors records to work out connection coverage; this tool is that answer. ⚠️ FOR A SILENT COVERAGE CHECK, CALL `well_get_connector_coverage` INSTEAD. Same scope arguments, same rows, no card. A data skill confirming a bank is connected before it measures anything must use that one: this tool renders on every call, so a check run here drops a connect picker into a conversation about something else and then waits for a click nobody meant to make. ⚠️ WAIT ON THE CARD IN THE TURN THAT DREW IT. Write your one line for the user FIRST — the wait holds the turn open for up to a minute, and a user looking at a card with no sentence beside it has been given no reason to click — then call `well_wait_for_selection` on the kind this result names in `next_step`. 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. - data_domains: the financial domains it serves — any of "bank", "accounting", "invoicing" — or null for a non-financial connector. One connector can serve several domains (Qonto serves all three). "bank" here means the connector delivers cash movements, which a payroll or billing platform also does; do NOT read it as "this is a bank". To list banks, pass kind: "bank", which the server scopes on its own bank classification. - invoice_source: this connector can bring supplier invoices into Well, either because it issues or holds them (an accounting or an invoicing tool) or because invoices arrive through it as files (a mailbox, a messaging app, a file drive). Read it to decide which tools to offer for a missing-invoice hunt. It is a property of the connector, not of this workspace's connection. - reason: why this row is on the card. "catalog" is the list that was asked for. "picked_vendor" is a connector behind a counterparty the user picked. Say which is which; never present a catalog row as one the user chose. - 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. - match_score: 0..1 confidence of that match; null when unmatched. A high score is a tool Well is confident the workspace already uses. - is_connected: this workspace has a connection you should REPAIR or MANAGE, not install fresh. True for "enabled", "processing", "error" and "need_reconnect"; false for "to_configure" and "disabled", where a fresh install IS the right next step. - connection_status: the existing connection's state, or null when this workspace has no connection row for the connector at all. One of: - "enabled" — connected and syncing. - "processing" — the grant is in and the FIRST sync is still running; data may be partial. Connected: do NOT ask the user to connect it again. - "error" — authenticated but its last real sync failed. Offer install_url as a reconnect. - "need_reconnect" — the grant is dead and only the user can restore it. Offer install_url as a reconnect, NOT a first install. - "to_configure" — a connect attempt that never completed its handshake. Nothing is connected: offer install_url as a first install, and never claim the tool is connected. - "disabled" — the connection was torn down. Offer install_url as a first install. A "degraded" connector never appears: it is resolved server-side against its own sync history into "enabled" or "error", so you never surface a state that clears itself. A connection whose state this build cannot read also reports null, and there is_connected stays true — read the two fields together, and treat "null status, is_connected true" as an existing connection whose health is unknown. - workspace_connector_id: the connection instance's id, or null when there is no connection row. This is the id well_invoke_connector_tool and well_list_connector_tools need — resolve it HERE, never via well_query_records on workspace_connectors. - last_successful_sync_at: ISO timestamp of the last SUCCESSFUL sync, or null when none has landed yet. An "enabled" connector with null here has a valid grant but has never delivered data. - sync_in_progress: a data sync is running right now. Tell the user to wait rather than to act. - is_preselected: Well recommends connecting this one now (a high-confidence match with is_connected false). The interactive picker pre-checks exactly these. A "to_configure" or "disabled" row can still be pre-checked — installing it IS the fix. On kind: "accounting" at most ONE row carries it — the single highest-confidence accounting tool — because connecting the accounting software is a pick-one step; every other scope pre-checks each high-confidence match. - install_url: a one-click link that STARTS or REPAIRS the connection in Well. It works from any state — it signs the user in if needed, creates their workspace if they have none, then runs the connector's own auth flow — and it covers banks too (a bank opens its bank-login flow pre-selected). Null only when the connector is not "available". Hand this to the user to get started in one click. - countries: the ISO 3166-1 alpha-2 countries this connector serves, or null when none is known. It is what the country scope sorts on; use it to explain why a bank fits the company, never to hide a bank the country field is null on. unsent_document_counts is a TOP-LEVEL field, present only when include_unsent_counts was passed. It names every tool this workspace forwards documents to, with the documents each one has not received yet, biggest backlog first. IT IS THE ONLY PLACE THE BACKLOG IS REPORTED: that array carries the workspace's whole set of outbound connections whatever catalog page came back, the connector rows carry no count at all, and the catalog runs to hundreds of rows, so a tool with a real backlog is missing from any page that did not happen to carry it. An entry reading 0 is a tool that is up to date: say nothing about it. unsent_document_count_is_upper_bound true means a document filter applies to that connection, so the count is a maximum and reads as "up to <n>". Every count is read off Well's own forward record, so it measures what Well wrote down rather than what the tool confirmed. Name each tool by the entry's name. install_all_url is a TOP-LEVEL field, not a per-connector one. It is ONE link that installs every installable connector in this result that is not already connected, in the order they are listed. Its reach is wider than the per-row links: a connector the catalog holds by service id alone carries a null install_url and is still installed by this link, so never read a null install_url as "cannot be installed". When the answer offers several connectors to install, hand the user install_all_url and do NOT list the per-connector install_url links beside it — the one link IS the whole offer, and a table of links beside it puts the reader back through several sign-ins. One link carries at most 10 connectors, and install_all_omitted names the service ids it left out, so offer those rows their own install_url. install_all_url is null when the result offers nothing to install. It is null too wherever the result names no set the user has chosen: the unfiltered catalog and the whole bank domain never carry the link, and a name search or an accounting or invoicing domain carries it only while the WHOLE result fits in one link and this page holds all of it — past that the link would stand for whichever rows the page happened to carry. from_selection always carries the link, however many vendors were picked, because the user named each one. Where install_all_url is null, the rows' own install_url links ARE the offer: list them, and never announce a batch link the result does not carry. Paging: page with offset and page_count, never with the length of connectors. On the first page of an unsearched browse the workspace's ALREADY CONNECTED connectors are prepended so the catalog's ordering cannot bury them past any page you would ask for — so connectors can be longer than the page it came from, and page_count is the catalog window's own length. Advance by offset + page_count; total counts every matching connector across all pages. Those prepended rows carry is_connected true (or a to_configure/disabled state), so a workspace's live tools are visible without paging for them. Scoping: pass kind ("bank" | "accounting" | "invoicing") to get only the connectors serving that domain — the whole set, server-ordered, including the long tail of bank institutions. Pass kind: "upload_surface" for the places invoices ARRIVE — mailboxes, messaging apps, file drives. Pass kind: "storage" for the drives Well FILES INTO — Google Drive, Dropbox, OneDrive — the step that asks where Well should write the documents it collects. Neither of those two is a financial domain: the server resolves each from the connectors' own display categories, so read the rows it returns and never re-derive the set from category_id yourself. They are opposite DIRECTIONS on the same drives, so a "storage" row carries direction "output" and no data_domains, and its is_connected reports the workspace's own file-drop connection, never the drive's separate invoice-source connection. Pass q to name-search the full catalog. Omit all of them for the curated, matched-first view. Use well_list_connector_tools for a live connection's actions. Country: pass country (ISO 3166-1 alpha-2, e.g. "FR") on a connect-a-bank step so the banks that serve the company's country sort first, then the ones that serve its region, then the rest. It reorders the page only — no row is dropped, and a country the catalog carries no coverage for is left in place — so a bank the user names is still found with q. Take the country from the workspace identity; omit it when the country is unknown, and the order is unchanged. Pass from_selection: true for the connect step that FOLLOWS a vendor pick. It returns the connectors behind the counterparties the user picked on the missing-invoices card in this conversation, and NOTHING else: only the picked vendors' connectors, and of those only the ones that can bring an invoice in (reason "picked_vendor"). It offers no accounting or invoicing tool the user did not pick: that offer belongs to its own step, scoped with kind. When the pick leaves no row, the list is empty and the card is not worth drawing. ⚠️ **This tool draws its card on EVERY call, the empty one included**, so never call it with from_selection to find out whether the pick has a connector behind it. Ask `well_get_worklist_status({ worklist: "invoice_sources_for_pick" })` first: it draws nothing, and it reports how many of the picked vendors carry a connector that can bring an invoice in. Make the from_selection call only when that count is above zero. An ABSENT count is not a zero: the probe answers `success: false` when it could not read the pick at all, so retry it rather than reading its silence as a vendor with no connector. row_count reports the same number back on this result. picked_vendors_filtered counts the picked vendors' connectors that were dropped for bringing no invoices in: when it is above zero, say a filter ran rather than letting a short card read as a pick nobody made. It takes no q and no kind: those browse a catalog, and this names a set already decided. An empty list means this conversation holds no pick for this workspace, or no picked counterparty matched a connector. Every result carries scope — "catalog", one of the three domains, "upload_surface", "storage", or "picked_vendors" — naming what the list IS. The card words its title from that field, so a caller must not describe the result as a domain the scope does not name.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'q': {'type': 'string', 'maxLength': 120, 'minLength': 1, 'description': 'Name search across the full catalog (e.g. a specific bank). Omit for the curated, matched-first view.'}, 'kind': {'enum': ['bank', 'accounting', 'invoicing', 'upload_surface', 'storage'], 'type': 'string', 'description': 'Scope the card server-side. Three financial domains: "bank" (every bank and neobank, including the long tail of open-banking institutions, plus the platforms that hold an account like Qonto and Pennylane — never a payroll or billing tool that merely reports transactions), "accounting", and "invoicing". Plus two scopes the server resolves from display categories rather than from a financial domain: "upload_surface", the places invoices ARRIVE (mailboxes, messaging apps, file drives), and "storage", the drives Well FILES INTO (Google Drive, Dropbox, OneDrive). The last two are opposite directions on the same drives, so a workspace can hold both connections and each is offered on its own card. Use this for a connect-a-bank, a connect-where-invoices-arrive or a connect-where-Well-files step instead of filtering the default view yourself. Omit for every connectable connector.'}, 'limit': {'type': 'integer', 'maximum': 100, 'minimum': 1, 'description': 'Max connectors to return (1-100, default 50).'}, 'title': {'type': 'string', 'maxLength': 120, 'description': 'Heading for the connect card shown to the user, OVERRIDING the wording the card otherwise derives from the scope/kind. Use it to frame the step in its flow (e.g. "Connect your accounting tool for the close"). At most 120 characters. Omit to keep the default wording for the requested kind.'}, 'offset': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0, 'description': 'Number of connectors to skip, for paging (default 0).'}, 'country': {'enum': ['AD', 'AE', 'AF', 'AG', 'AI', 'AL', 'AM', 'AO', 'AQ', 'AR', 'AS', 'AT', 'AU', 'AW', 'AX', 'AZ', 'BA', 'BB', 'BD', 'BE', 'BF', 'BG', 'BH', 'BI', 'BJ', 'BL', 'BM', 'BN', 'BO', 'BQ', 'BR', 'BS', 'BT', 'BV', 'BW', 'BY', 'BZ', 'CA', 'CC', 'CD', 'CF', 'CG', 'CH', 'CI', 'CK', 'CL', 'CM', 'CN', 'CO', 'CR', 'CU', 'CV', 'CW', 'CX', 'CY', 'CZ', 'DE', 'DJ', 'DK', 'DM', 'DO', 'DZ', 'EC', 'EE', 'EG', 'EH', 'ER', 'ES', 'ET', 'FI', 'FJ', 'FK', 'FM', 'FO', 'FR', 'GA', 'GB', 'GD', 'GE', 'GF', 'GG', 'GH', 'GI', 'GL', 'GM', 'GN', 'GP', 'GQ', 'GR', 'GS', 'GT', 'GU', 'GW', 'GY', 'HK', 'HM', 'HN', 'HR', 'HT', 'HU', 'ID', 'IE', 'IL', 'IM', 'IN', 'IO', 'IQ', 'IR', 'IS', 'IT', 'JE', 'JM', 'JO', 'JP', 'KE', 'KG', 'KH', 'KI', 'KM', 'KN', 'KP', 'KR', 'KW', 'KY', 'KZ', 'LA', 'LB', 'LC', 'LI', 'LK', 'LR', 'LS', 'LT', 'LU', 'LV', 'LY', 'MA', 'MC', 'MD', 'ME', 'MF', 'MG', 'MH', 'MK', 'ML', 'MM', 'MN', 'MO', 'MP', 'MQ', 'MR', 'MS', 'MT', 'MU', 'MV', 'MW', 'MX', 'MY', 'MZ', 'NA', 'NC', 'NE', 'NF', 'NG', 'NI', 'NL', 'NO', 'NP', 'NR', 'NU', 'NZ', 'OM', 'PA', 'PE', 'PF', 'PG', 'PH', 'PK', 'PL', 'PM', 'PN', 'PR', 'PS', 'PT', 'PW', 'PY', 'QA', 'RE', 'RO', 'RS', 'RU', 'RW', 'SA', 'SB', 'SC', 'SD', 'SE', 'SG', 'SH', 'SI', 'SJ', 'SK', 'SL', 'SM', 'SN', 'SO', 'SR', 'SS', 'ST', 'SV', 'SX', 'SY', 'SZ', 'TC', 'TD', 'TF', 'TG', 'TH', 'TJ', 'TK', 'TL', 'TM', 'TN', 'TO', 'TR', 'TT', 'TV', 'TW', 'TZ', 'UA', 'UG', 'UM', 'US', 'UY', 'UZ', 'VA', 'VC', 'VE', 'VG', 'VI', 'VN', 'VU', 'WF', 'WS', 'YE', 'YT', 'ZA', 'ZM', 'ZW'], 'type': 'string', 'description': 'The company\'s country as an ISO 3166-1 alpha-2 code (e.g. "FR"). When set, the connectors that serve that country sort first, then the ones that serve its region, then the rest — the order only, no row is dropped. Use it on a connect-a-bank step so the banks that fit the company appear first; take it from the workspace identity\'s country. Omit when the country is unknown, and the order is left unchanged.'}, 'subtitle': {'type': 'string', 'maxLength': 240, 'description': "Supporting line under the connect card's heading, OVERRIDING the scope-derived subtitle. At most 240 characters. Omit to keep the default wording for the requested kind."}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. This read reports one workspace's own data. Omit it and the token's primary workspace answers, which may not be the one you mean; the result names the workspace that did."}, 'from_selection': {'type': 'boolean', 'const': True, 'description': "Scope the card to the connectors behind the counterparties the user picked on the missing-invoices card in this conversation, each installable one pre-checked. Use it for the connect step that FOLLOWS a vendor pick. It returns those vendors' connectors and NOTHING else: a picked connector that brings no invoices in is dropped, and no accounting or invoicing tool the user did not pick is offered here: that offer is its own step, scoped with `kind`. Cannot be combined with `q` or `kind`: those name a catalog to browse, and this names a set already decided. Returns an empty list when this conversation holds no pick for this workspace, or when no picked counterparty matched a connector."}, 'conversation_id': {'type': 'string', '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.'}, 'include_unsent_counts': {'type': 'boolean', 'const': True, 'description': "Add the top-level `unsent_document_counts`: every tool Well forwards this workspace's documents to, each with how many documents it has not received yet. That array is the whole answer — it holds every one of the workspace's outbound connections, whatever catalog page was requested, and the rows carry no count at all. Off by default, because it costs an extra read. The figure is the workspace's whole backlog, not a period's."}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['install_all_url', 'install_all_omitted', 'success'], 'properties': {'error': {'type': 'string'}, 'limit': {'type': 'number', 'description': 'The page size that was REQUESTED. The catalog may return fewer.'}, 'scope': {'enum': ['catalog', 'bank', 'accounting', 'invoicing', 'upload_surface', 'storage', 'picked_vendors'], 'type': 'string', 'description': "What this result is a list OF: the requested kind, the picked vendors' connectors, or the curated catalog when neither was asked for. The card words itself from this, so it never describes the rows as a domain that was not requested."}, 'total': {'type': 'number', 'description': 'Every connector matching the query, across all pages — NOT the length of `connectors`.'}, 'offset': {'type': 'number', 'description': 'How many catalog rows this page skipped.'}, 'success': {'type': 'boolean'}, 'next_step': {'type': 'string', 'description': 'What to do with the card this result renders. Added by the dispatcher when the card asks for a click.'}, 'row_count': {'type': 'number', 'description': 'How many rows this result puts ON THE CARD, prepended rows included. `0` on a `picked_vendors` scope means the pick has no connector behind it that can bring an invoice in: the card carries nothing to tick, so say so in half a sentence and move on. Not a paging cursor — `page_count` is.'}, 'connectors': {'type': 'array', 'items': {'type': 'object', 'required': ['service_id', 'name', 'category_id', 'status', 'direction', 'data_domains', 'invoice_source', 'reason', 'logo_url', 'popularity_score', 'is_matched', 'is_selected', 'match_score', 'is_connected', 'connection_status', 'workspace_connector_id', 'last_successful_sync_at', 'sync_in_progress', 'is_preselected', 'install_url', 'countries'], 'properties': {'name': {'type': 'string'}, 'reason': {'enum': ['catalog', 'picked_vendor'], 'type': 'string'}, 'status': {'type': 'string'}, 'logo_url': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'countries': {'anyOf': [{'type': 'array', 'items': {'type': 'string'}}, {'type': 'null'}]}, 'direction': {'type': 'string'}, 'is_matched': {'type': 'boolean'}, 'service_id': {'type': 'string'}, 'category_id': {'type': 'string'}, 'install_url': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'is_selected': {'type': 'boolean'}, 'match_score': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'data_domains': {'anyOf': [{'type': 'array', 'items': {'enum': ['bank', 'accounting', 'invoicing'], 'type': 'string'}}, {'type': 'null'}]}, 'is_connected': {'type': 'boolean'}, 'invoice_source': {'type': 'boolean'}, 'is_preselected': {'type': 'boolean'}, 'popularity_score': {'anyOf': [{'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, {'type': 'null'}]}, 'sync_in_progress': {'type': 'boolean'}, 'connection_status': {'anyOf': [{'enum': ['enabled', 'processing', 'error', 'need_reconnect', 'to_configure', 'disabled'], 'type': 'string'}, {'type': 'null'}]}, 'workspace_connector_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'last_successful_sync_at': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}}, 'page_count': {'type': 'number', 'description': "The catalog page's own length, and the ONLY safe paging cursor: advance by `offset + page_count`. `connectors` can be LONGER — on the first page of an unsearched browse the workspace's already-connected rows are prepended so they cannot be lost to the catalog's ordering — so paging by the array's length silently skips exactly that many catalog rows on every later request."}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'install_all_url': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "One link that installs every installable connector in this result. Null when the result offers nothing to install, or when its scope names a set the reader has not chosen. When it is non-null it is the ONLY install link the answer offers — do not list the rows' own install_url beside it. When it is null, the rows' own install_url is the offer instead."}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'install_all_omitted': {'type': 'array', 'items': {'type': 'string'}, 'description': 'The service ids install_all_url could not carry, because one link names a bounded number of connectors. Offer these rows their own install_url instead of promising the batch link covers them.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}, 'unsent_document_counts': {'type': 'array', 'items': {'type': 'object', 'required': ['service_id', 'name', 'workspace_connector_id', 'unsent_document_count', 'unsent_document_count_is_upper_bound'], 'properties': {'name': {'type': 'string'}, 'service_id': {'type': 'string'}, 'unsent_document_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'workspace_connector_id': {'type': 'string'}, 'unsent_document_count_is_upper_bound': {'type': 'boolean'}}, 'additionalProperties': False}, 'description': "Every tool this workspace forwards documents to, each with the documents it has not received yet, biggest backlog first. Present only when `include_unsent_counts` was set. THIS IS THE ONLY PLACE THE BACKLOG IS REPORTED: it is not a page, it carries the workspace's whole set of outbound connections whether or not the requested catalog page holds their rows, and the catalog rows carry no count. An empty array means the workspace forwards to nothing; an absent field means nothing was measured. `unsent_document_count_is_upper_bound: true` means a document filter applies to that connection, so the count is a maximum and reads as `up to <n>`. Every count is read off Well's own forward record, so it measures what Well wrote down rather than what the tool confirmed. Name a tool by its `name`. An entry reading `0` is a tool that is up to date: say nothing about it."}, 'picked_vendors_filtered': {'type': 'number', 'description': "How many of the picked vendors' connectors were dropped for bringing no invoices in. Present on the `picked_vendors` scope only. Above zero means the card is SHORTER than the pick: say that those vendors' tools cannot deliver an invoice, rather than letting the gap read as a pick the user never made."}}, 'additionalProperties': False}

well_list_connector_tools

List connector tools

Discover the actions a connected provider exposes (e.g. "what can I do with Attio?"). WORKFLOW: 1. well_list_connectors() → pick the ENABLED provider (connection_status: "enabled") and read its workspace_connector_id directly off the row. 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.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['workspace_connector_id'], 'properties': {'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. This read reports one workspace's own data. Omit it and the token's primary workspace answers, which may not be the one you mean; the result names the workspace that did."}, 'conversation_id': {'type': 'string', '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.'}, 'workspace_connector_id': {'type': 'string', 'minLength': 1, 'description': "The connected provider's workspace_connector_id (from well_list_connectors)."}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'error': {'type': 'string'}, 'tools': {'type': 'array', 'items': {'type': 'object', 'required': ['name'], 'properties': {'name': {'type': 'string'}, 'description': {'type': 'string'}, 'inputSchema': {'type': 'object', 'propertyNames': {'type': 'string'}, 'additionalProperties': {}}}, 'additionalProperties': False}}, 'total': {'type': 'number'}, 'status': {'type': 'string'}, 'success': {'type': 'boolean'}, 'usage_notes': {'type': 'string'}, 'reconnect_url': {'type': 'string'}, 'connector_slug': {'type': 'string'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_list_counterparties

List counterparties

List the workspace's counterparty companies and how each one is CATEGORIZED — the company-level industry labels a counterparty carries. Use it for "which suppliers have no category?", "what industries are my counterparties in?", and before categorizing a counterparty so you name real ids instead of guessing. Name a scope, and say whether to keep only the ones missing a category: - `periods: [{ calendar_year, calendar_month }, …]` (1-12): the counterparties whose invoices those months are still missing, categorized ones included, each row tagged with its month and carrying `tx_count`, `base_total_amount` in `base_currency`, and `suggested_retrieval`. Every month must have ended. - `periods` PLUS `uncategorized_only: true`: the same months, keeping ONLY the counterparties that carry no category. Use this whenever the question is which of a period's suppliers still need one, and whenever a step asks the user to categorize them: the categorized ones are not the work, and listing them buries it. - `uncategorized_only: true` alone: a WORKSPACE-WIDE sweep for every counterparty that carries no category, no month involved. Returns 50 rows per page plus `total_count`; `tx_count`, `base_total_amount` and `suggested_retrieval` are null because the call names no period. When `next_cursor` is not null the sweep has more counterparties: call again with `cursor` set to it to read them. It is a POSITION, not a row offset, so categorizing the rows of one page never hides the rows of the next. Only this sweep pages: `cursor` is refused beside `periods`. - `missing_ledger_only: true` alone: the LEDGER-ASSIGNMENT worklist — the counterparties that have a bank transaction and still need a ledger account (COA) default set for the direction their transactions take. Its rows ride in `ledger_rows`, not `rows`, each carrying `needs_payable`/`needs_receivable` and the AP/AR default it holds now; a needed slot is empty, assigned from the chart of accounts. This is a DIFFERENT question from categorization: it assigns a ledger account, not an industry label. Set a default with `well_update_company({ account_payable_default_id | account_receivable_default_id })`; read the account ids with `well_list_ledger_accounts`. It returns the first 500 counterparties needing a default, so a worklist that fills 500 (`total_count` equal to `row_count` at 500) is a FLOOR: assign those and read the scope again for the rest. It is its own scope — never combine it with `periods`, `uncategorized_only`, or `cursor`. COST: the period form has no batch endpoint, so each named month is a separate read of that month's spend. Ask for the months the user actually named, not a whole year "to be safe". Every row carries `categories` (`[{ category_id, name }]`) and `is_categorized`. `categorized_count` and `uncategorized_count` count the COUNTERPARTIES OF THE SCOPE, once each however many months they appear in, not the rows returned. Under `uncategorized_only` the result lists the uncategorized ones alone while `categorized_count` still counts the ones it withheld, so the two together are the period's coverage and `uncategorized_count` is the work left. Report both: naming the listed rows as the period's whole counterparty set overstates how much is uncategorized. TO SET a counterparty's categories, call `well_update_company({ company_id, category_ids: [...] })` — that field REPLACES the company's whole set. Read the available labels first with `well_query_records({ root: "categories", whereClause: { category_type: { _eq: "company" } } })`: that is the company-category catalog. It has no curated allowlist — the labels are minted during enrichment — so pass ids from it rather than inventing a taxonomy. `suggested_retrieval` is derived from the PROVIDER match, not from the category. Categorizing a counterparty does not change it; do not tell the user otherwise. This tool only reads. It categorizes nothing, mints no task, connects nothing and fetches no invoice. No workspace read is needed first: the workspace is resolved from the caller's authorized token, same as every other well_* tool. When the user asks to see, list or fix these rows, call this tool directly: its card is the answer. ⚠️ **This tool draws its card on EVERY call, the empty one included.** So when nobody asked for the list and you only need to CHECK whether anything is left (the first pass of a gate, or a re-check after a repair), call `well_get_worklist_status({ worklist: "counterparties_to_categorize", periods })` first, with the same scope you would pass here. It draws nothing. Call this tool after it only when it answers `open: true`.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'cursor': {'type': 'string', 'description': 'The next page of the workspace-wide uncategorized sweep: pass back the `next_cursor` the previous call returned. Only that sweep pages, so this needs `uncategorized_only: true` and NO `periods`, because a period scope returns every month it covers in one call.'}, 'periods': {'type': 'array', 'items': {'type': 'object', 'required': ['calendar_year', 'calendar_month'], 'properties': {'calendar_year': {'type': 'integer', 'maximum': 2100, 'minimum': 2000, 'description': 'Calendar year, e.g. 2026.'}, 'calendar_month': {'type': 'integer', 'maximum': 12, 'minimum': 1, 'description': 'Calendar month, 1 = January … 12 = December.'}}, 'additionalProperties': False}, 'maxItems': 12, 'minItems': 1, 'description': "The calendar months whose counterparties to list, 1-12. Each month costs one separate read of that month's spend. Duplicates are refused."}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. This read reports one workspace's own data. Omit it and the token's primary workspace answers, which may not be the one you mean; the result names the workspace that did."}, 'conversation_id': {'type': 'string', '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.'}, 'uncategorized_only': {'type': 'boolean', 'const': True, 'description': "Keep only the counterparties that carry no industry category. WITH `periods`: the uncategorized counterparties OF those months. Use it whenever the question is which of a period's suppliers still need a category. WITHOUT `periods`: a WORKSPACE-WIDE sweep for every uncategorized counterparty, 50 rows per page plus the total, with a `next_cursor` for the page after this one."}, 'missing_ledger_only': {'type': 'boolean', 'const': True, 'description': 'A workspace-wide sweep for the counterparties that have a bank transaction and still need a ledger account (COA) default set for the direction their transactions take — the ledger-assignment worklist. It is its OWN scope: never pass it with `periods`, `uncategorized_only`, or `cursor`. Each row carries `needs_payable`/`needs_receivable` and the AP/AR defaults it holds now (a needed slot is empty), and rides in `ledger_rows` rather than `rows`.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['rows', 'success'], 'properties': {'mode': {'enum': ['periods', 'uncategorized_only', 'missing_ledger_only'], 'type': 'string', 'description': 'Which SCOPE the call asked for; the row fields that are populated follow from it. `periods` whenever the call named months, whether or not it also filtered to the uncategorized ones. `missing_ledger_only` returns its rows in `ledger_rows`, not `rows`.'}, 'rows': {'type': 'array', 'items': {'type': 'object', 'required': ['company_id', 'name', 'domain', 'logo_url', 'calendar_year', 'calendar_month', 'period_label', 'tx_count', 'base_total_amount', 'categories', 'is_categorized', 'suggested_categories', 'suggested_retrieval'], 'properties': {'name': {'type': 'string'}, 'domain': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'logo_url': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "The company's stored logo; null when enrichment has not landed one."}, 'tx_count': {'anyOf': [{'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, {'type': 'null'}], 'description': 'Transactions missing an invoice in the period. Null on the sweep.'}, 'categories': {'type': 'array', 'items': {'type': 'object', 'required': ['category_id', 'name'], 'properties': {'name': {'type': 'string'}, 'category_id': {'type': 'string'}}, 'additionalProperties': False}, 'description': 'The industry categories this counterparty carries; empty when none.'}, 'company_id': {'type': 'string'}, 'period_label': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': 'The month this row belongs to, e.g. "June 2026". Null on the sweep.'}, 'calendar_year': {'anyOf': [{'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, {'type': 'null'}], 'description': 'Null on the uncategorized sweep, which names no period.'}, 'calendar_month': {'anyOf': [{'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, {'type': 'null'}], 'description': 'Null on the uncategorized sweep, which names no period.'}, 'is_categorized': {'type': 'boolean'}, 'base_total_amount': {'anyOf': [{'type': 'number'}, {'type': 'null'}], 'description': "Sum in base_currency of the period's transactions missing an invoice. Null on the sweep, and null when an FX rate was missing."}, 'suggested_retrieval': {'anyOf': [{'enum': ['agent', 'upload', 'connect'], 'type': 'string'}, {'type': 'null'}], 'description': "How the app currently offers to obtain this counterparty's invoices: agent (a browser agent runs the supplier portal), connect (connect the matched service and Well fetches them), upload (the user supplies the file). Derived from the PROVIDER match, NOT from the categories — the category does not select a retrieval path today. Null on the uncategorized sweep, which has no period to route."}, 'suggested_categories': {'type': 'array', 'items': {'type': 'object', 'required': ['category_id', 'name', 'confidence', 'rank', 'reasoning'], 'properties': {'name': {'type': 'string'}, 'rank': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': "1 is the classifier's top proposal."}, 'reasoning': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "The classifier's own account of this proposal, or null when the run stored none."}, 'confidence': {'type': 'number', 'description': "0..1, the classifier's own scale."}, 'category_id': {'type': 'string', 'description': 'The catalog id of the proposed label — pass it straight to `well_update_company` to accept it.'}}, 'additionalProperties': False}, 'description': "A stored classifier PROPOSAL is a candidate label, never a decision: `categories` is what this counterparty actually carries, and only a write makes a proposal true. Highest confidence first, at most three. Empty when the classifier has not run, abstained, or a human already resolved its proposal — an empty array is not evidence that no label fits. Present on both scopes. Report a proposal as a suggestion to the user, never as the counterparty's industry, and NOTE this is unrelated to `suggested_retrieval`, which is about fetching invoices."}}, 'additionalProperties': False}}, 'error': {'type': 'string'}, 'hints': {'type': 'array', 'items': {'type': 'string'}}, 'success': {'type': 'boolean'}, 'next_step': {'type': 'string', 'description': 'What to do with the card this result renders. Added by the dispatcher when the card asks for a click.'}, 'row_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'ledger_rows': {'type': 'array', 'items': {'type': 'object', 'propertyNames': {'type': 'string'}, 'additionalProperties': {}}}, 'next_cursor': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "The uncategorized sweep's next page: pass it back as `cursor`. Null when this page ends the sweep, absent on the periods scope, which pages nothing."}, 'total_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': "Counterparties MATCHING the call, before the row cap, so a capped sweep says what it left out. On the periods scope: the DISTINCT counterparties `rows` names, and a multi-month call lists one counterparty on one row per month, so row_count can exceed it. Under `uncategorized_only` it counts the uncategorized ones alone; the scope's whole population is `categorized_count` plus `uncategorized_count`. Under `missing_ledger_only` it is the worklist actually returned and equals `row_count`: that scope reads the first 500 counterparties needing a default, so a worklist that fills 500 is a FLOOR, not a complete count. Assign those and read the scope again for the rest."}, 'workspace_id': {'type': 'string'}, 'base_currency': {'type': 'string'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'periods_covered': {'type': 'array', 'items': {'type': 'object', 'required': ['calendar_year', 'calendar_month', 'period_label'], 'properties': {'period_label': {'type': 'string', 'description': 'The month this row belongs to, e.g. "June 2026".'}, 'calendar_year': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'calendar_month': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}}, 'additionalProperties': False}, 'description': 'The months the result covers, oldest first.'}, 'categorized_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'COUNTERPARTIES of the scope that carry at least one category, counted over the whole scope, not over `rows`, and counted once however many months a counterparty appears in. Under `uncategorized_only` these are exactly the counterparties the result withheld, so a non-zero figure beside rows that are all uncategorized is the coverage, not a contradiction.'}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'uncategorized_only': {'type': 'boolean', 'description': 'Whether `rows` holds ONLY the counterparties that carry no category. True on the workspace-wide sweep and on a period scope the call filtered. When true, `categorized_count` counts counterparties the result did NOT list.'}, 'uncategorized_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': "COUNTERPARTIES of the scope that carry none, counted the same way. This is the outstanding work; with `categorized_count` it is the scope's whole population."}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_list_ledger_accounts

List ledger accounts

List the workspace's chart of accounts (COA) — every ledger account a counterparty default or a transaction can be assigned to. Use it to name a real `ledger_account_id` in a write instead of guessing one. Each account carries `id` (the `ledger_account_id` the writes take), `name`, and `code` (its account number, e.g. "401" for a vendor or "411" for a customer under the FR PCG) where the account has one. `truncated: true` means the chart holds MORE accounts than this page carries; read the rest with `well_query_records` on the `ledger_accounts` root. **`success: false` means the chart could not be read, NOT that the workspace has none.** An empty `accounts` on a failed read is unknown, never "no chart of accounts". When the token authorizes one workspace, call this directly — no other tool call is needed first. When it authorizes several, this read will not guess which one you mean: pass `workspace_id` on the call.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'limit': {'type': 'integer', 'maximum': 500, 'minimum': 1, 'description': 'Max accounts to return; the chart is capped either way.'}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which."}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['accounts', 'success'], 'properties': {'error': {'type': 'string'}, 'success': {'type': 'boolean'}, 'accounts': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'name'], 'properties': {'id': {'type': 'string'}, 'code': {'type': 'string'}, 'name': {'type': 'string'}}, 'additionalProperties': False}}, 'returned': {'type': 'number'}, 'truncated': {'type': 'boolean'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_list_member_candidates

List member candidates

List the teammates a workspace can invite, exactly as the Well app's invite card shows them. Use it before well_invite_members, and for "who can I invite to this workspace?". Returns `candidates`, each with `person_id`, `name`, `email`, `avatar_url`, a `state` (`active` already has access, `pending` was invited and has not accepted, `not_member` can be invited), and a `source` (`detected` shares the workspace owner's corporate email domain, `provided` was named in `person_ids` or resolved from the assigned gap owners). Never invite a candidate whose state is `active`. Alongside them it returns `targets` — this workspace plus any workspace group you belong to, each an option for where the invite lands — `roles` (`admin` or `member`, with a hint), and `me_person_id` so you never offer to invite the caller. Three ways to source the candidates: - Default: the detected same-domain teammates who hold no membership. - `person_ids`: resolve specific people you already hold the ids for, with their membership state. Set `include_detected` false to return only those. - `from_assigned_gaps: true`: resolve the owners of the settled expense transactions still missing a supplier invoice for the period, server-side, with their membership state — the invite step of a close or fetch flow uses this so it never depends on remembering who was assigned on the owner card. It returns only those owners (the detected teammates are omitted). Name the period ONE way — `{ calendar_year, calendar_month }` or `{ fiscal_year, fiscal_period }` — or name no period to use the months selected on the period card this session. Every month must have ended. ⚠️ WAIT ON THE CARD IN THE TURN THAT DREW IT. Write your one line for the user FIRST, then call `well_wait_for_selection({ kind: "invite_ack" })`, which this result's `next_step` also states. The card's own footer sends the invitations and writes the acknowledgement, so never call `well_invite_members` yourself after a click. The outcome the click carries says which button it was: "done" sent the invitations, "keep_for_later" set the step aside. Both end the step. When the token authorizes one workspace, call this directly — no other tool call is needed first. When it authorizes several, this read will not guess which one you mean: pass `workspace_id` on the call.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'person_ids': {'type': 'array', 'items': {'type': 'string', '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)$'}, 'maxItems': 100, 'minItems': 1, 'description': 'Person ids to resolve with their membership state (the `provided` source).'}, 'fiscal_year': {'type': 'integer', 'maximum': 2100, 'minimum': 2000, 'description': "Fiscal year (the calendar year the workspace's fiscal year STARTED in). `from_assigned_gaps` only."}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which."}, 'calendar_year': {'type': 'integer', 'maximum': 2100, 'minimum': 2000, 'description': 'Calendar year, e.g. 2026. `from_assigned_gaps` only.'}, 'fiscal_period': {'type': 'integer', 'maximum': 13, 'minimum': 1, 'description': 'Fiscal period, 1-12. `from_assigned_gaps` only, paired with `fiscal_year`. The adjustment period (13) is refused.'}, 'calendar_month': {'type': 'integer', 'maximum': 12, 'minimum': 1, 'description': 'Calendar month, 1 = January … 12 = December. `from_assigned_gaps` only, paired with `calendar_year`.'}, 'conversation_id': {'type': 'string', '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.'}, 'include_detected': {'type': 'boolean', 'description': 'Omit the detected same-domain teammates when false. Defaults to true.'}, 'from_assigned_gaps': {'type': 'boolean', 'description': "Resolve the candidates from the owners of the period's missing-invoice gaps, server-side, instead of `person_ids`. The detected teammates are omitted, and `include_detected` is treated as false."}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['candidates', 'targets', 'roles', 'me_person_id', 'success'], 'properties': {'error': {'type': 'string'}, 'roles': {'type': 'array', 'items': {'type': 'object', 'required': ['value', 'label', 'hint'], 'properties': {'hint': {'type': 'string'}, 'label': {'type': 'string'}, 'value': {'enum': ['admin', 'member'], 'type': 'string'}}, 'additionalProperties': False}, 'description': 'The assignable roles, `admin` or `member`, each with a one-line hint.'}, 'success': {'type': 'boolean'}, 'targets': {'type': 'array', 'items': {'type': 'object', 'required': ['kind', 'id', 'name', 'workspace_count'], 'properties': {'id': {'type': 'string'}, 'kind': {'enum': ['workspace', 'group'], 'type': 'string'}, 'name': {'type': 'string'}, 'workspace_count': {'anyOf': [{'type': 'number'}, {'type': 'null'}], 'description': 'How many workspaces a group holds; null for the workspace target.'}}, 'additionalProperties': False}, 'description': 'Where an invite can land: this workspace, plus any workspace group the caller belongs to.'}, 'next_step': {'type': 'string', 'description': 'What to do with the card this result renders. Added by the dispatcher when the card asks for a click.'}, 'candidates': {'type': 'array', 'items': {'type': 'object', 'required': ['person_id', 'name', 'email', 'avatar_url', 'state', 'source', 'invite_expires_at'], 'properties': {'name': {'type': 'string'}, 'email': {'type': 'string'}, 'state': {'enum': ['not_member', 'pending', 'active'], 'type': 'string', 'description': '`active` already has access; `pending` was invited and not yet accepted; `not_member` can be invited.'}, 'source': {'enum': ['detected', 'provided'], 'type': 'string', 'description': "`detected` shares the workspace owner's email domain; `provided` was named by the caller's person_ids."}, 'person_id': {'type': 'string'}, 'avatar_url': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'invite_expires_at': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': 'When a `pending` invite lapses; null on every other state.'}}, 'additionalProperties': False}}, 'me_person_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "The caller's own person id, so the card never offers to invite them."}, 'workspace_id': {'type': 'string'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_list_missing_invoice_owners

List missing-invoice owners

List the settled expense TRANSACTIONS a past period is still missing a supplier invoice for, one row per line, each with its current owner SET. Use it for "who owes the missing invoices?" and as the input to well_assign_missing_invoice_owners. Each row reports its TRANSACTION owner SET. An empty `owners` set means no transaction owner set was found; it does not prove that no card rule or other legacy owner exists. The `bucket` is `no_owner_set`, `assigned_to_me`, or `assigned_to_others`, computed from that set against the calling person. This lists the SAME missing invoices well_list_missing_invoices shows, but flattened to lines you can assign; there is no per-card grouping and no `scope: "card"`. Name the period ONE way: `{ calendar_year, calendar_month }`, `{ fiscal_year, fiscal_period }`, or `periods: [...]` for several months (1-12), or name NO period to use the months selected on the period card in this conversation. Every month must have ended. Each row carries `transaction_id` (pass it to well_assign_missing_invoice_owners), `date`, `description`, `counterparty` (name, id, and logo when a provider was matched), `amount`, `currency`, and `base_amount`. Rows with no owner set come first, then the caller's own, then those owned only by others; `no_owner_set_count`, `assigned_to_me_count`, and `assigned_to_others_count` summarize the split over the returned rows. The rows per counterparty are a BOUNDED sample (`sampled: true`), so `row_count` may be fewer than `transaction_count` — the window's true total — and `transactions_omitted` is the difference. Use it to assign owners, not to count a period's total gaps; well_list_missing_invoices carries the full per-counterparty totals. This tool reads the user's data and changes none of it. When the token authorizes one workspace, call this directly — no other tool call is needed first. When it authorizes several, this read will not guess which one you mean: pass `workspace_id` on the call.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'periods': {'type': 'array', 'items': {'type': 'object', 'required': ['calendar_year', 'calendar_month'], 'properties': {'calendar_year': {'type': 'integer', 'maximum': 2100, 'minimum': 2000, 'description': 'Calendar year, e.g. 2026.'}, 'calendar_month': {'type': 'integer', 'maximum': 12, 'minimum': 1, 'description': 'Calendar month, 1 = January … 12 = December.'}}, 'additionalProperties': False}, 'maxItems': 12, 'minItems': 1, 'description': 'Several calendar months in one call, 1-12. Each month costs one separate read, so name only the months you need. Duplicates are refused.'}, 'fiscal_year': {'type': 'integer', 'maximum': 2100, 'minimum': 2000, 'description': "Fiscal year (the calendar year the workspace's fiscal year STARTED in)."}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which."}, 'calendar_year': {'type': 'integer', 'maximum': 2100, 'minimum': 2000, 'description': 'Calendar year, e.g. 2026.'}, 'fiscal_period': {'type': 'integer', 'maximum': 13, 'minimum': 1, 'description': 'Fiscal period, 1-12. The adjustment period (13) is refused: it has no calendar month.'}, 'calendar_month': {'type': 'integer', 'maximum': 12, 'minimum': 1, 'description': 'Calendar month, 1 = January … 12 = December.'}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['transactions', 'success'], 'properties': {'error': {'type': 'string'}, 'sampled': {'type': 'boolean', 'description': "True always: each counterparty's rows are a bounded sample, so a counterparty whose every gap fell outside the sample is under-represented. Use it to assign owners, not to count a period's total gaps."}, 'success': {'type': 'boolean'}, 'next_step': {'type': 'string', 'description': 'What to do with the card this result renders. Added by the dispatcher when the card asks for a click.'}, 'row_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Transaction rows returned in `transactions` (a bounded sample per counterparty).'}, 'me_person_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "The calling person, against which each row's `bucket` is computed; null when the token carries no person."}, 'transactions': {'type': 'array', 'items': {'type': 'object', 'required': ['transaction_id', 'date', 'description', 'counterparty', 'amount', 'currency', 'base_amount', 'owners', 'bucket', 'period'], 'properties': {'date': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "The line's posting date (YYYY-MM-DD), or null when undated."}, 'amount': {'anyOf': [{'type': 'number'}, {'type': 'null'}], 'description': 'The line amount in `currency`, sign preserved (negative = money out); null when unknown.'}, 'bucket': {'enum': ['no_owner_set', 'assigned_to_me', 'assigned_to_others'], 'type': 'string', 'description': "This line's transaction owner set relative to the caller: no owner set, includes the caller, or includes only others."}, 'owners': {'type': 'array', 'items': {'type': 'object', 'required': ['person_id', 'name'], 'properties': {'name': {'type': 'string'}, 'person_id': {'type': 'string'}}, 'additionalProperties': False}, 'description': "The line's live transaction owner set, highest-precedence first. Empty means no owner set was found; it does not prove that no card rule or other legacy owner exists."}, 'period': {'type': 'object', 'required': ['calendar_year', 'calendar_month', 'period_label'], 'properties': {'period_label': {'type': 'string', 'description': 'The month this row belongs to, e.g. "June 2026".'}, 'calendar_year': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'calendar_month': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}}, 'description': 'The month this line belongs to.', 'additionalProperties': False}, 'currency': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'base_amount': {'anyOf': [{'type': 'number'}, {'type': 'null'}], 'description': "The same amount in `base_currency`, sign preserved; null when no rate covered the line's date."}, 'description': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "The bank's remittance text; may be null."}, 'counterparty': {'type': 'object', 'required': ['company_id', 'name', 'logo_url', 'mode', 'matched_connector_service_id'], 'properties': {'mode': {'anyOf': [{'enum': ['agent', 'connect', 'upload'], 'type': 'string'}, {'type': 'null'}], 'description': 'How the missing document can be collected, after the same downgrade rules the missing-invoices card applies; null when no route resolved. Word the retrieval affordance off this, never off a name.'}, 'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'logo_url': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "The matched provider's logo, when one was matched to this counterparty; else null."}, 'company_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'matched_connector_service_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': 'The connector standing for a `connect` route; null for a route with no matched connector.'}}, 'additionalProperties': False}, 'transaction_id': {'type': 'string', 'description': "Pass this to well_assign_missing_invoice_owners to set the line's owner set."}}, 'additionalProperties': False}, 'description': "The missing-invoice lines, with no owner set first, then the caller's own, then those owned only by others."}, 'base_currency': {'type': 'string'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'periods_covered': {'type': 'array', 'items': {'type': 'object', 'required': ['calendar_year', 'calendar_month', 'period_label'], 'properties': {'period_label': {'type': 'string', 'description': 'The month this row belongs to, e.g. "June 2026".'}, 'calendar_year': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'calendar_month': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}}, 'additionalProperties': False}, 'description': 'The months the result covers, oldest first.'}, 'transaction_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Total missing-invoice transactions the window holds across all counterparties, sampled or not.'}, 'no_owner_set_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Returned rows with no transaction owner set.'}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'assigned_to_me_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Returned rows whose transaction owner set includes the caller.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'transactions_omitted': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Missing-invoice transactions the window holds beyond the returned sample (`transaction_count` − `row_count`).'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}, 'assigned_to_others_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Returned rows whose transaction owner set includes only other people.'}}, 'additionalProperties': False}

well_list_missing_invoices

List missing invoices

List the supplier invoices a past period is still missing — the settled spend whose invoice has not been collected, one row per counterparty, exactly as the Well app's expense-invoices card shows them. Use it for "which invoices am I missing for <month>?" and as the input to fetching them. Name the period ONE way: `{ calendar_year, calendar_month }` (the calendar month, e.g. June 2026 → 2026, 6), `{ fiscal_year, fiscal_period }`, or `periods: [{ calendar_year, calendar_month }, …]` for SEVERAL months in one call (1-12), or name NO period at all to use the months the user selected on the period card in this conversation (well_list_periods → the user clicks → well_switch_workspace records them). With no period named and no months selected, the call refuses and tells you to run the period step first. Every month must have ended: a current or future month is refused, and so is the adjustment period (13). Duplicate months are refused. COST: there is no batch endpoint, so each named month is a separate read of that month's spend. Ask for the months the user actually named, not a whole year "to be safe". Returns `rows`, ONE per counterparty for the whole call, never one per month. Each row carries `name`, `tx_count` and `base_total_amount` in `base_currency` SUMMED over the months it covers, its own `months` array naming those months (each with that month's `tx_count`, `base_total_amount`, `proof_task_id`, `acquisition_status` and `refusal_reason`), and the route fields `mode`, `available_modes`, `suggested_action`, `matched_provider_name` and `matched_connector_service_id`, which the provider match resolves once per counterparty. NEVER list a counterparty once per month and never present its months as separate gaps: it is one supplier to chase, and one collection covers every month behind it. Name the months a row spans from its `months` array. The envelope's own `months` carries each month's totals (rows are NOT repeated there), `periods_covered` names the months read, and `transaction_count`, `group_count` and `dropped_groups` are totals across every month read. `row_count` counts the DISTINCT counterparties, so it is never the sum of the months' own `row_count`. `dropped_groups` counts the GROUPS that produced no row — party-less bank operations, unresolved counterparties, unnamed companies — never transactions, and `bank_internal` and `unknown` hold one group per month whatever they contain, so quote neither as a quantity of operations. `unknown` and `unnamed_company` ARE categorized expense spend still missing a supplier invoice, so an empty `rows` over a non-zero count is not a complete period; `bank_internal` alone is, since no supplier can invoice a party-less operation. The single-month fields `calendar_year`, `calendar_month`, `fiscal_year`, `fiscal_period` and `period_label` appear ONLY when the call named exactly one month. Every row also carries `transactions` — the counterparty's own lines behind the row, each with `date`, `description` (the bank's remittance text), `category`, `amount`, `currency` and `base_amount`. `amount` is signed and stays in the transaction's own currency, so never add those together across a row; `base_amount` is the same line in `base_currency`, and the magnitudes of those DO add up to `base_total_amount`. The list is capped at 25 per row and `transactions_omitted` says how many the cap left out — quote that number instead of implying the list is complete. `mode` is the ONE route the card suggests for that row: `agent` (a browser agent can collect it from the supplier portal), `connect` (connect the named service and Well fetches it), `upload` (the user supplies the file). `available_modes` lists every route the row offers instead of only the suggested one — `agent` and `upload` on every row, plus `connect` when the catalog holds a connector for the matched provider, so 2 or 3 entries. Present `mode` as the suggestion and `available_modes` as the choice. Only CATEGORIZED expense transactions are considered — uncategorized spend is not listed, so poor categorization coverage under-reports the gaps; disclose the `hints`. This tool reads the user's data and changes none of it. It does not mint tasks, start a close, connect anything, or fetch any invoice. Call this directly — no other tool call is needed first (workspace is resolved from the caller's authorized token, same as every other well_* tool).

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'periods': {'type': 'array', 'items': {'type': 'object', 'required': ['calendar_year', 'calendar_month'], 'properties': {'calendar_year': {'type': 'integer', 'maximum': 2100, 'minimum': 2000, 'description': 'Calendar year, e.g. 2026.'}, 'calendar_month': {'type': 'integer', 'maximum': 12, 'minimum': 1, 'description': 'Calendar month, 1 = January … 12 = December.'}}, 'additionalProperties': False}, 'maxItems': 12, 'minItems': 1, 'description': 'Several calendar months in one call, 1-12. Each month costs one separate read, so name only the months you need. Duplicates are refused.'}, 'fiscal_year': {'type': 'integer', 'maximum': 2100, 'minimum': 2000, 'description': "Fiscal year (the calendar year the workspace's fiscal year STARTED in)."}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. This read reports one workspace's own data. Omit it and the token's primary workspace answers, which may not be the one you mean; the result names the workspace that did."}, 'calendar_year': {'type': 'integer', 'maximum': 2100, 'minimum': 2000, 'description': 'Calendar year, e.g. 2026.'}, 'fiscal_period': {'type': 'integer', 'maximum': 13, 'minimum': 1, 'description': 'Fiscal period, 1-12. The adjustment period (13) is refused: it has no calendar month.'}, 'calendar_month': {'type': 'integer', 'maximum': 12, 'minimum': 1, 'description': 'Calendar month, 1 = January … 12 = December.'}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['rows', 'success'], 'properties': {'rows': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'company_id', 'name', 'logo_url', 'domain_resolution', 'months', 'tx_count', 'transactions', 'transactions_omitted', 'base_total_amount', 'mode', 'available_modes', 'suggested_action', 'matched_provider_name', 'matched_provider_url', 'matched_provider_has_blueprint', 'matched_connector_service_id'], 'properties': {'id': {'type': 'string', 'description': 'Stable row key: the counterparty company id, or the proof task id of a gap that resolved no company. One key per counterparty for the whole call, so it never repeats across the months the row covers.'}, 'mode': {'enum': ['agent', 'upload', 'connect'], 'type': 'string', 'description': "How the app's card offers to obtain the invoice: agent (a browser agent runs the supplier portal — the provider carries a blueprint OR a real portal URL the agent runs against), connect (connect matched_connector_service_id and Well fetches it), upload (the user supplies the file). Decided from the provider facts: connect wins when a connector matched, else agent when it can run, else upload."}, 'name': {'type': 'string'}, 'months': {'type': 'array', 'items': {'type': 'object', 'required': ['calendar_year', 'calendar_month', 'period_label', 'tx_count', 'base_total_amount', 'proof_task_id', 'acquisition_status', 'refusal_reason'], 'properties': {'tx_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Transactions this counterparty is missing an invoice for in THIS month alone.'}, 'period_label': {'type': 'string', 'description': 'The month this row belongs to, e.g. "June 2026".'}, 'calendar_year': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'proof_task_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "The close-proof task bound to this month's gap; null until one is minted."}, 'calendar_month': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'refusal_reason': {'anyOf': [{'enum': ['noop_not_proof', 'noop_no_gap_match', 'noop_ambiguous_gaps', 'noop_task_unavailable', 'warn_bridge_error'], 'type': 'string'}, {'type': 'null'}], 'description': "Populated only when THIS month's acquisition_status is refused."}, 'base_total_amount': {'anyOf': [{'type': 'number'}, {'type': 'null'}], 'description': "This month's sum in `base_currency`; null when an FX rate was missing for any of its transactions."}, 'acquisition_status': {'enum': ['waiting', 'processing', 'mapped', 'refused'], 'type': 'string'}}, 'additionalProperties': False}, 'description': "The months of the call this counterparty is missing an invoice in, oldest first: one entry, or several when the same counterparty owes an invoice in more than one of them. The envelope's `periods_covered` names every month READ; this names the months THIS row covers."}, 'logo_url': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "The counterparty's mark: the matched provider's stored logo, else the counterparty company's own stored logo — the one company enrichment resolved from that company's domain. Null when the row matched no provider and its company carries no stored logo. A null here does not mean the card draws initials: the widget is additionally offered a mark derived from the company's own host, which this field never carries."}, 'tx_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Transactions missing an invoice, summed across every month in `months`.'}, 'company_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'transactions': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'date', 'description', 'category', 'category_key', 'amount', 'currency', 'base_amount'], 'properties': {'id': {'type': 'string'}, 'date': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': 'The day the transaction posts under (YYYY-MM-DD); null when it carries no date.'}, 'amount': {'anyOf': [{'type': 'number'}, {'type': 'null'}], 'description': 'Signed amount in `currency` — negative when the money leaves the account.'}, 'category': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "Display label of THIS transaction's management category, not the group's. Null when uncategorized."}, 'currency': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'base_amount': {'anyOf': [{'type': 'number'}, {'type': 'null'}], 'description': 'The same amount converted to `base_currency`, still signed. Sum the magnitudes of these to reach `base_total_amount`; null when no FX rate covered the date.'}, 'description': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "The bank's remittance text — what distinguishes one line from the next. Null when the row carries none."}, 'category_key': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': 'Stable taxonomy key of the same category — branch on this, never on the label. Null when off-catalog.'}}, 'additionalProperties': False}, 'description': "The row's own transactions, oldest month first, at most 25 for the WHOLE row: the same bounded sample the app's card lists under the counterparty. A row spanning months carries one sample across them, not one per month."}, 'available_modes': {'type': 'array', 'items': {'enum': ['agent', 'connect', 'upload'], 'type': 'string'}, 'description': 'Every collection method this counterparty offers, agent first and upload last — 2 or 3 entries, never one. `agent` and `upload` stand for every row; `connect` joins them only when the catalog holds a connector for the matched provider, which is exactly what a non-null matched_connector_service_id reports. `mode` names the ONE route the card suggests, this names all the routes the user may pick.'}, 'suggested_action': {'enum': ['connect_provider', 'chrome_extension_fetch', 'manual_upload'], 'type': 'string', 'description': "The backend's routing decision for the row. `chrome_extension_fetch` when the matched provider can run the browser agent (a blueprint or a real portal URL), `connect_provider` when a connector matched, else `manual_upload`. `mode` is the same decision in the card's vocabulary."}, 'base_total_amount': {'anyOf': [{'type': 'number'}, {'type': 'null'}], 'description': 'Sum in base_currency across every month in `months`; null when an FX rate was missing for any transaction of any of them.'}, 'domain_resolution': {'enum': ['resolved', 'pending', 'none'], 'type': 'string', 'description': "The counterparty company's own domain-discovery state: 'resolved' when it already carries a domain (any source); 'pending' when a web-evidence resolve is durably enqueued and still open; 'none' when no domain is known and nothing is in flight."}, 'matched_provider_url': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'transactions_omitted': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': "How many of the row's transactions the cap left out: `tx_count` minus the listed ones."}, 'matched_provider_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'matched_connector_service_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'matched_provider_has_blueprint': {'type': 'boolean'}}, 'additionalProperties': False}, 'description': "The card's rows, ONE per counterparty for the whole call, in the order the oldest month listed them, each naming the months it covers in `months`. A counterparty owing an invoice in several of the months read is one row, never one per month."}, 'error': {'type': 'string'}, 'hints': {'type': 'array', 'items': {'type': 'string'}}, 'months': {'type': 'array', 'items': {'type': 'object', 'required': ['calendar_year', 'calendar_month', 'period_label', 'fiscal_year', 'fiscal_period', 'row_count', 'transaction_count', 'group_count', 'dropped_groups'], 'properties': {'row_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': "Counterparties THIS month is missing an invoice from. A counterparty owing an invoice in several months counts in each of them, so these do not sum to the envelope's `row_count`, which counts each counterparty once."}, 'fiscal_year': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'group_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'period_label': {'type': 'string'}, 'calendar_year': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'fiscal_period': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'calendar_month': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'dropped_groups': {'type': 'object', 'required': ['bank_internal', 'unknown', 'unnamed_company'], 'properties': {'unknown': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'GROUPS of spend with no resolved counterparty. One group per month that held any, NOT a count of transactions or of counterparties.'}, 'bank_internal': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'GROUPS of party-less bank operations — nothing to collect. One group per month that held any, NOT a count of operations: never quote this number as a quantity of bank operations.'}, 'unnamed_company': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'GROUPS the card cannot render (no name or no key) — one per company, NOT a count of transactions.'}}, 'additionalProperties': False}, 'transaction_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}}, 'additionalProperties': False}, 'description': 'Per-month totals, oldest first.'}, 'success': {'type': 'boolean'}, 'next_step': {'type': 'string', 'description': 'What to do with the card this result renders. Added by the dispatcher when the card asks for a click.'}, 'row_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': "Rows in `rows`, which is the DISTINCT counterparties the call found. Never the sum of the months' own `row_count`."}, 'fiscal_year': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Present only when the call named exactly one month.'}, 'group_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': "Groups the reads returned before the card's projection."}, 'period_label': {'type': 'string', 'description': 'Human-readable label of the period, e.g. "June 2026". Present only when the call named one month.'}, 'workspace_id': {'type': 'string'}, 'base_currency': {'type': 'string'}, 'calendar_year': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Present only when the call named exactly one month.'}, 'fiscal_period': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Present only when the call named exactly one month.'}, 'calendar_month': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Present only when the call named exactly one month.'}, 'dropped_groups': {'type': 'object', 'required': ['bank_internal', 'unknown', 'unnamed_company'], 'properties': {'unknown': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'GROUPS of spend with no resolved counterparty. One group per month that held any, NOT a count of transactions or of counterparties.'}, 'bank_internal': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'GROUPS of party-less bank operations — nothing to collect. One group per month that held any, NOT a count of operations: never quote this number as a quantity of bank operations.'}, 'unnamed_company': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'GROUPS the card cannot render (no name or no key) — one per company, NOT a count of transactions.'}}, 'additionalProperties': False}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'periods_covered': {'type': 'array', 'items': {'type': 'object', 'required': ['calendar_year', 'calendar_month', 'period_label'], 'properties': {'period_label': {'type': 'string', 'description': 'The month this row belongs to, e.g. "June 2026".'}, 'calendar_year': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'calendar_month': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}}, 'additionalProperties': False}, 'description': 'The months the result covers, oldest first.'}, 'periods_requested': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'How many calendar months the call named.'}, 'transaction_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Every transaction missing its invoice, across all groups and all months.'}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_list_periods

List periods

List the recent accounting months of the workspace, with each month's close status, its invoice-retrieval state, and the counts that describe how much work it holds. Use this to ask the user WHICH month or months to work on before any close, review, or month-scoped read — do not guess a month, and do not derive one from today's date yourself. Each entry carries: - calendar_year / calendar_month: the month itself. - fiscal_year / fiscal_period: the same month in the workspace's fiscal calendar — this is the pair every close endpoint and close tool takes. - label: the month written out, e.g. "March 2026". - is_complete: the calendar month has ended. A still-accruing month is never a valid close target. - selectable: the month can be CLOSED. False for a month that has not ended, one already closed, one with nothing to close, and a December whose year-end close is not supported yet. Read this one for a close pick. - analyzable: the month can be REPORTED ON. True once the month has ENDED and while it remains inside the window the canvas endpoints serve; false for the month in progress, for a future month, and for one too far back. It does NOT ask for a close verdict, because a report reads transactions and an unchecked month still has them. Read this one for an analysis pick. - inspectable: the month can be LOOKED INTO. A reader can open its transactions, its missing invoices and its days. True for EVERY month that has begun, the month in progress included. False only for a month that has not begun. It reads no close verdict and no activity count, so a closed month, an empty month and a workspace with no accounting connector at all still have readable months. An empty month answers with an empty list, which is an answer. Read this one for a retrieval or review pick; every selectable month is also inspectable. - close_status: "closeable" (ready), "not_ready" (work remains), "closed" (already locked), "nothing_to_close" (no activity), or null when the workspace has no verdict for that month. - close_reason: the blocking reason behind the status, or null. - invoice_state: "missing_invoices" (at least one counterparty still owes a supplier invoice), "has_invoices" (checked, and nothing is missing), or "none" (no state: no activity, the month has not begun, or the check could not run). Never read "none" as "nothing missing". - missing_invoice_count: how many counterparties owe an invoice for the month — the rows `well_list_missing_invoices` would return. 0 whenever invoice_state is "none", including when the check did not run. - transaction_count: how many transactions the month holds, dated on the basis this purpose measures on. `analysis` counts on `executed_at`, the same column `well_sum_transactions` ranges, so a month's count and a reporting figure cover the same WINDOW. It is not the same row set, and must never be quoted as the figure's row count: the sum can also drop internal transfers and exempt categories on request, and it widens to a parent's granted transactions where this count does not. Read it as a presence signal for the month. `close` and `collect` count on the books date, `COALESCE(value_date, booking_date)`, which a transaction the bank has not booked does not carry — so a zero under those purposes means no BOOKED transaction, never an empty month. - bank_transaction_count: the subset of transaction_count delivered by a connector the workspace actually BANKS with, meaning a bank, a neobank, or a treasury or spend platform whose product is an account. An accounting platform and a payment processor deliver transactions too, so transaction_count is NOT a bank signal. Only this field answers "has a bank fed this month". A transaction counts as not-bank when its source connector is unknown, or when that connector has since been disconnected, so a zero here never licenses skipping a bank-connection step. - unposted_invoice_count: invoices the month HAS that have not posted to the ledger. This is a posting gap, not a missing invoice — do not present it as one. - uncategorized_transactions: transactions in the month not yet categorized — the "help categorize" errand behind a not-ready close. Dated on the books, so it is ABSENT under `analysis` rather than 0 — that purpose counts on execution and never measures this errand, and a 0 would read as "nothing left to categorize". It is also absent on a month the coverage read did not cover. Never read an absent count as "nothing left to categorize": say the month was not measured, or read it again. - categorized_unposted_transactions: categorized transactions not yet posted to the ledger — part of the "review and book" errand. Dated on the books, absent under `analysis`, and absent on an unmeasured month for the same reason. - invoice_state / missing_invoice_count: the month's invoice-retrieval verdict and the count behind it. Both are ABSENT on a month a `analysis` list skipped — that purpose bounds its invoice read by execution-dated activity while the errand is dated on the books, so the two disagree and a "none" there would be a claim nothing measured. Absent is not "owes nothing"; read it from a `close` or `collect` list. - days: the DAYS of the month that carry a retrieval state, ascending, each `{ day, state }` over the same vocabulary as invoice_state. A day is "missing_invoices" when it holds settled expense spend still missing its supplier invoice, and "has_invoices" when it holds activity and no such gap. Days with neither are OMITTED, so an absent day means "none". `days` is empty for every month whose invoice_state is "none" — an unchecked month has no day the tool can call clean — and it is empty for EVERY month on a `purpose: "analysis"` call, whatever that month's invoice_state, because the reporting axis paints no day. On that purpose an empty `days` therefore says nothing about invoice coverage, and neither does an absent invoice_state. This is calendar detail for a picker to paint; quote the month's own counts, not a day list, when answering in prose. - analysis_days: present ONLY for a `purpose: "analysis"` call — the DAYS and whether a breakdown can name what each holds, ascending, each `{ day, state }` over "categorized" / "uncategorized" / "neutral". An "uncategorized" day holds a transaction with no category. It still COUNTS toward a burn total, which filters on no category at all; a cost breakdown just reports it as uncategorised rather than under a named category. Never say a total is short because of it. Unlike the other two axes a quiet day IS listed, as "neutral". Calendar detail for the reporting picker. - close_days: present ONLY for a `purpose: "close"` call — the DAYS carrying a non-neutral close-readiness state, ascending, each `{ day, state }` over "posted" / "progress". A day absent from it is "neutral" (nothing to close). Calendar detail for the close picker, like `days` is for retrieval. `default_period` is the oldest month that is ready to close, falling back to the oldest still in progress. Offer it as the default choice. It reads `selectable`, so it is null whenever no month in the window can be CLOSED, and a null one does not mean the window is empty: an inspectable month can still be worked on for invoice retrieval. On a `purpose: "analysis"` call it is instead the NEWEST `analyzable` month, because a figure describes the latest ended period and a month outside the reporting window would be refused by the endpoints that serve it. PURPOSE: pass `purpose: "close"` when the user is closing the books, so the picker paints close readiness and each month carries its `close_days` and the categorize / review counts. Pass `purpose: "analysis"` when a REPORTING SKILL is already running and is choosing the month its figure will cover, so the picker offers only `analyzable` months and paints the CATEGORIZATION day axis: neither invoice coverage nor close readiness is the decision being made, but an uncategorized day is one a breakdown cannot attribute. A user who merely mentions a report, a burn figure or a cost breakdown is NOT the trigger — naming one of those is phrasing, and phrasing never sets this field. Example: "What months do you have for me? I'm trying to work out my average burn." is a plain listing request that names a reason — it is NOT a reporting skill calling for its own period pick, so this call OMITS `purpose`. Only a caller that IS the reporting flow itself (an `avg-burn`/`cost-structure`/`cash-flow-waterfall` skill run, already past its own gates, now needing the month to compute against) passes "analysis" — never derive it from words in the user's own message, no matter how closely they match a report. Omit it (or `purpose: "collect"`) for invoice retrieval, the default. This is the calling skill's intent — set it from the flow, never from the user's phrasing. WINDOW: by default the `months` most recent calendar months, ending with the current one. Pass `year` instead to get ONE calendar year in full — all twelve of its months, December back to January — which is how you reach a year the recent window does not cover, backwards or forwards. `navigable_years` reports the range `year` is answered for. A year ahead of today comes back in full and every month of it is `selectable: false` and `inspectable: false` with `close_reason` "period_not_ended": books close on a month that has ENDED, and a month that has not begun holds nothing to read. Show such months when the user asks to look ahead, and say why they cannot be picked. Never omit them. COST: the invoice state is read per month from a separate endpoint, so a wide window costs one extra read for every month that holds activity, plus one day-coverage read per calendar year those months touch. A `purpose: "analysis"` call pays the same day-coverage read, dated on the execution basis, because it paints the categorization day axis. Ask for the months the user needs, not 24 by default. A wholly future or wholly empty `year` is cheap — no month in it can hold a settled gap, so none is read. Call this directly — no other tool call is needed first (the workspace is resolved from the caller's authorized token, same as every other well_* tool).

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'year': {'type': 'integer', 'maximum': 2100, 'minimum': 2000, 'description': 'One calendar year to return in full — all twelve of its months, December back to January, instead of the recent window. Use it to reach a year the recent window does not cover, in either direction; future months come back visible but never selectable. Accepted range: 2000-2100, also reported as `navigable_years`.'}, 'reply': {'type': 'string', 'maxLength': 160, 'minLength': 1, 'description': 'One sentence, IN THE LANGUAGE THE USER IS WRITING IN, that the click sends into the conversation as their own message. Write what the PERSON would say about the months they pick, in their words, not an instruction to yourself. You write it BEFORE they click, so you cannot know what they will choose: put {picked} where the pick belongs and the card replaces it with the names they actually picked, one or several. In English it would read "Let\'s work on {picked}." Write the same shape in the user\'s language. {picked} is required: a sentence that names a pick itself names the one you guessed, so the card refuses it and sends its own English instead. At most 160 characters. Omitted sends an English sentence the card builds itself, which is wrong for any reader not writing in English.'}, 'title': {'type': 'string', 'maxLength': 120, 'description': 'Heading for the picker card shown to the user. At most 120 characters.'}, 'months': {'type': 'integer', 'default': 12, 'maximum': 24, 'minimum': 1, 'description': 'How many recent calendar months to return, ending with the current month. Each month holding activity costs one extra read for its invoice state. Ignored when `year` is given.'}, 'purpose': {'enum': ['close', 'collect', 'analysis'], 'type': 'string', 'description': 'Why the months are being listed, set by the calling skill\'s own flow — never inferred from this message. "close" is book closure: the card paints close readiness, and each month carries its per-day `close_days` and the counts behind its "why not ready" errands. "analysis" is reporting: the card offers only the months a canvas can report on, paints the categorization day axis, counts on the execution date the canvas aggregates measure on, and therefore omits the books-dated errand counts entirely rather than reporting them as 0 — set it ONLY when a reporting skill is already running its own period-pick step, not just because this message names one (a burn figure, a cost breakdown, "my report"). Naming a report is phrasing; it never sets this field on its own. Omit or "collect" for invoice retrieval (the default, and the right choice for a plain "what months do you have" question, even one that mentions why) — this paints the retrieval axis and skips the close-readiness fields.'}, 'subtitle': {'type': 'string', 'maxLength': 240, 'description': "Supporting line under the picker card's heading. At most 240 characters."}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. This read reports one workspace's own data. Omit it and the token's primary workspace answers, which may not be the one you mean; the result names the workspace that did."}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['workspace_id', 'fiscal_year_start_month', 'base_currency', 'periods', 'default_period', 'navigable_years', 'success'], 'properties': {'error': {'type': 'string'}, 'hints': {'type': 'array', 'items': {'type': 'object', 'required': ['detected_gap', 'suggested_action', 'severity'], 'properties': {'field': {'type': 'string'}, 'severity': {'enum': ['warn', 'info'], 'type': 'string'}, 'detected_gap': {'type': 'string'}, 'suggested_action': {'type': 'string'}}, 'additionalProperties': False}}, 'periods': {'type': 'array', 'items': {'type': 'object', 'required': ['calendar_year', 'calendar_month', 'fiscal_year', 'fiscal_period', 'label', 'is_complete', 'selectable', 'inspectable', 'analyzable', 'close_status', 'close_reason', 'transaction_count', 'bank_transaction_count', 'unposted_invoice_count', 'days'], 'properties': {'days': {'type': 'array', 'items': {'type': 'object', 'required': ['day', 'state'], 'properties': {'day': {'type': 'integer', 'maximum': 31, 'minimum': 1}, 'state': {'enum': ['has_invoices', 'missing_invoices', 'none'], 'type': 'string'}}, 'additionalProperties': False}, 'description': 'Days of the month carrying a retrieval state, ascending. A day absent from this list is "none"; the list is empty whenever invoice_state is "none", and is ALWAYS empty on a "analysis" call, which paints the categorization axis instead — so an empty list there carries no invoice claim.'}, 'label': {'type': 'string'}, 'analyzable': {'type': 'boolean', 'description': 'The month can be REPORTED ON — an average-burn, cost-structure or cash-bridge figure can be computed for it. True once the month has ENDED and while it stays inside the window the canvas endpoints serve. Read this one for an analysis pick.'}, 'close_days': {'type': 'array', 'items': {'type': 'object', 'required': ['day', 'state'], 'properties': {'day': {'type': 'integer', 'maximum': 31, 'minimum': 1}, 'state': {'enum': ['posted', 'progress', 'neutral'], 'type': 'string'}}, 'additionalProperties': False}, 'description': 'Days of the month carrying a non-neutral close-readiness state, ascending. Present ONLY for a "close" call; a day absent from it is "neutral" (nothing to close).'}, 'selectable': {'type': 'boolean', 'description': 'The month can be CLOSED. False while it is still running.'}, 'fiscal_year': {'type': 'number'}, 'inspectable': {'type': 'boolean', 'description': 'The month can be LOOKED INTO. A reader can open its transactions, missing invoices and days. True for every month that has begun, the month in progress included, whatever its close verdict and however little it holds. False only for a month that has not begun. Every selectable month is also inspectable.'}, 'is_complete': {'type': 'boolean'}, 'close_reason': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'close_status': {'anyOf': [{'enum': ['closeable', 'closed', 'not_ready', 'nothing_to_close'], 'type': 'string'}, {'type': 'null'}]}, 'analysis_days': {'type': 'array', 'items': {'type': 'object', 'required': ['day', 'state'], 'properties': {'day': {'type': 'integer', 'maximum': 31, 'minimum': 1}, 'state': {'enum': ['categorized', 'uncategorized', 'neutral'], 'type': 'string'}}, 'additionalProperties': False}, 'description': 'Days of the month and whether a breakdown can name what each one holds, ascending. Present ONLY for a "analysis" call. "uncategorized" means the day holds a transaction with no category — still counted in a burn total, but reported as uncategorised in a breakdown rather than under a named category; "categorized" means they all carry one; "neutral" means the day holds no transaction. Unlike the other two axes, a quiet day IS listed, as "neutral" — so a day absent from a non-empty list is one the read did not reach. An EMPTY list means the month was not measured at all, never that it holds nothing to categorize: check transaction_count, which is read separately, and treat a positive count beside an empty list as unmeasured. Calendar detail for the picker; quote the month\'s own counts in prose, not a day list.'}, 'calendar_year': {'type': 'number'}, 'fiscal_period': {'type': 'number'}, 'invoice_state': {'enum': ['has_invoices', 'missing_invoices', 'none'], 'type': 'string', 'description': 'The month\'s invoice-retrieval verdict. ABSENT on a month that has BEGUN and whose verdict nothing measured, which only a purpose counting on the execution date produces — its activity read and this books-dated errand disagree, so "none" there would be a claim nothing wrote. A month still ahead of today keeps "none" on every purpose, because it owes nothing on every basis. Read an absent one from a "close" or "collect" list.'}, 'calendar_month': {'type': 'number'}, 'transaction_count': {'type': 'number', 'description': 'How many transactions the month holds, dated on the basis this purpose measures on: "analysis" counts on execution, every other purpose on the books. A presence signal for the month, never the row count behind a reported figure.'}, 'missing_invoice_count': {'type': 'number', 'description': 'Counterparties owing a supplier invoice for the month; 0 when invoice_state is "none". Absent whenever invoice_state is, and for the same reason.'}, 'bank_transaction_count': {'type': 'number', 'description': 'The transaction_count subset delivered by a connector the workspace BANKS with, meaning its category is `banks` or its service id is on the bank-account list. An accounting platform and a payment processor deliver transactions too and are not counted. A transaction whose source connector is unknown, or since disconnected, is not counted either, so a 0 never licenses skipping a bank-connection step.'}, 'unposted_invoice_count': {'type': 'number', 'description': 'Invoices the month holds that have not posted to the ledger — NOT missing invoices.'}, 'uncategorized_transactions': {'type': 'number', 'description': 'Transactions in the month not yet categorized — the \'help categorize\' close errand. Dated on the books, so it is ABSENT on a "analysis" call rather than 0: that purpose counts on execution and never measures this errand. Absent too on a month the coverage read did not cover. An absent count is never "nothing left to categorize".'}, 'categorized_unposted_transactions': {'type': 'number', 'description': 'Categorized transactions not yet posted to the ledger — part of the \'review and book\' close errand. Dated on the books, and likewise ABSENT rather than 0 on a "analysis" call and on a month the coverage read did not cover.'}}, 'additionalProperties': False}}, 'success': {'type': 'boolean'}, 'next_step': {'type': 'string', 'description': 'What to do with the card this result renders. Added by the dispatcher when the card asks for a click.'}, 'workspace_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'base_currency': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'default_period': {'anyOf': [{'type': 'object', 'required': ['calendar_year', 'calendar_month'], 'properties': {'calendar_year': {'type': 'number'}, 'calendar_month': {'type': 'number'}}, 'additionalProperties': False}, {'type': 'null'}]}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'navigable_years': {'type': 'object', 'required': ['earliest', 'latest'], 'properties': {'latest': {'type': 'number'}, 'earliest': {'type': 'number'}}, 'description': "The calendar years a `year` request is answered for. A picker's year steppers stop here.", 'additionalProperties': False}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}, 'fiscal_year_start_month': {'type': 'number'}}, 'additionalProperties': False}

well_list_recurring_contexts

List the billing contexts a reader can count as recurring

List the billing contexts a reader can count as recurring revenue over one window, each with what counting it would add. This is what the recurring-contexts card offers; it measures nothing `well_sum_invoices` did not already measure. Each entry in `groups` is one billing context's revenue in the window: `context_key` (the id a selection is matched on), `label` (the context as the product writes it), `amounts` (one entry per currency, each already net of credit notes and never converted) and `count` (the invoices behind it). The named contexts are sorted biggest first in the currency that carries the most invoices, so the biggest decision reads first. A context whose window nets to nothing in every currency is NOT listed — counting it would add nothing, so it is not a choice. A context that nets NEGATIVE stays on the list: its credit notes outweighed its invoices, which is a real state, and hiding it would move the figure by an amount nobody saw. **The last entry may be `context_key: "unclassified"`, labelled "No billing context".** It is the invoices whose `billing_context` is `null`: extraction fills the field rather than a billing system, so on most workspaces it holds most of the revenue. It is a choice like the others. A business that bills only subscriptions can count it as recurring; a business with one-off work usually cannot. When the reader counts it, apply it to the `well_sum_invoices` rows whose `billing_context` is `null` — no row carries the key itself. **State its amount whenever it is listed**, counted or not, because it is the part of the figure extraction could not describe. `totals` is the sum of the groups' amounts per currency: the window's whole readable issued revenue. **This read converts nothing and never adds one currency to another.** The reader decides per context, so the choice needs no single total; convert once, in the arithmetic, at a rate you state. This read takes no view on which contexts ARE recurring, and offers no default, the "No billing context" entry included. What counts as recurring revenue is a fact about the reader's business, not about the vocabulary: a retainer is recurring for one company and a one-off engagement for another. Take the reader's answer from the card: its Continue records it with `well_switch_workspace` as `recurring_contexts`, and you read it back with `well_wait_for_selection` (kind "recurring_contexts"). Keep only the `well_sum_invoices` rows whose `billing_context` is in that answer, reading `unclassified` as the rows whose `billing_context` is `null`, and pass the same keys to `well_render_mrr` as `recurring_contexts` so the figure names what it counted. The window is whole months: `from` and `to` are both the first day of a month, YYYY-MM-01, `from` inclusive and `to` EXCLUSIVE. `window` echoes both back exactly as you sent them. When a comparison will be measured, read the list over BOTH windows, from the start of the earlier one to the end of this one, so a context that stopped billing between them is still offered. `partial: true` means the aggregate was cut short: every amount here is a FLOOR, a context's real share can only be larger, and a choice made because a share looked small may not survive the full read. Say so before presenting the list as a basis for the decision. `unreadable_rows` counts invoices whose net amount or currency could not be read at all; they are in no figure here. It is `null` when that count could not be read, which is not zero: say it is unmeasured. Read `success` before `groups`: a failed read returns no contexts, which looks exactly like a window with nothing to choose. When the token authorizes one workspace, call this directly — no other tool call is needed first. When it authorizes several, this read will not guess which one you mean: pass `workspace_id` on the call.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['from', 'to'], 'properties': {'to': {'type': 'string', 'pattern': '^(\\d{4})-(\\d{2})-01$', 'description': 'EXCLUSIVE end of the window: the first day of the month after the last one you want, YYYY-MM-01.'}, 'from': {'type': 'string', 'pattern': '^(\\d{4})-(\\d{2})-01$', 'description': 'Inclusive start of the window: the first day of a month, YYYY-MM-01.'}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which."}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['groups', 'totals', 'partial', 'unreadable_rows', 'window', 'success'], 'properties': {'error': {'type': 'string'}, 'groups': {'type': 'array', 'items': {'type': 'object', 'required': ['context_key', 'label', 'amounts', 'count'], 'properties': {'count': {'type': 'number'}, 'label': {'type': 'string'}, 'amounts': {'type': 'array', 'items': {'type': 'object', 'required': ['currency', 'amount'], 'properties': {'amount': {'type': 'number'}, 'currency': {'type': 'string'}}, 'additionalProperties': False}}, 'context_key': {'type': 'string'}}, 'additionalProperties': False}}, 'totals': {'type': 'array', 'items': {'type': 'object', 'required': ['currency', 'amount'], 'properties': {'amount': {'type': 'number'}, 'currency': {'type': 'string'}}, 'additionalProperties': False}}, 'window': {'type': 'object', 'required': ['from', 'to'], 'properties': {'to': {'type': 'string'}, 'from': {'type': 'string'}}, 'additionalProperties': False}, 'partial': {'type': 'boolean', 'description': 'True when the aggregate behind these figures was cut short. Every amount is then a FLOOR rather than a measurement.'}, 'success': {'type': 'boolean'}, 'next_step': {'type': 'string', 'description': 'What to do with the card this result renders. Added by the dispatcher when the card asks for a click.'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'unreadable_rows': {'anyOf': [{'type': 'number'}, {'type': 'null'}], 'description': 'Invoices in the window whose net amount or currency could not be read. They are in no figure here, including the no-billing-context one. Null when the count could not be read.'}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_list_retargetable_connectors

List retargetable connectors

Read the connectors on this workspace's lineage parent (its membership workspace) that could follow it here, WITHOUT showing the user anything: each candidate's connector, how strongly it was proved to belong to this company, and how much transaction history is behind it. This draws nothing on the user's screen and asks for no confirmation. Use it ONLY for a silent CHECK the model acts on itself: the close-books bank step deciding whether a candidate exists on the parent before it offers the retarget card, a step that needs the candidate count. An empty list is the normal answer for a workspace connected correctly the first time. Read the count and act in the same turn — there is no card and no click to wait on. ⚠️ To have the USER bring a connector across, call `well_show_retargetable_connectors` INSTEAD — that one draws the card the user confirms. This tool cannot draw one, so a retarget step run here leaves the user with nothing to act on.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which."}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'error': {'type': 'string'}, 'success': {'type': 'boolean'}, 'next_step': {'type': 'string', 'description': 'What to do with the card this result renders. Added by the dispatcher when the card asks for a click.'}, 'candidates': {'type': 'array', 'items': {'type': 'object', 'required': ['workspace_connector_id', 'service_id', 'name', 'proof_tier', 'transaction_count', 'earliest_transaction_date', 'latest_transaction_date', 'source_workspace', 'preselected'], 'properties': {'name': {'type': 'string'}, 'proof_tier': {'enum': ['canonical_id', 'name_country', 'no_match'], 'type': 'string'}, 'service_id': {'type': 'string'}, 'preselected': {'type': 'boolean'}, 'source_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'type': 'string'}, 'workspace_id': {'type': 'string', '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)$'}}, 'additionalProperties': False}, 'transaction_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'workspace_connector_id': {'type': 'string', '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)$'}, 'latest_transaction_date': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'earliest_transaction_date': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_list_uncategorized_window

List uncategorized transactions in a window

List the transactions in a date window that carry no category, so a figure that depends on categorization can say exactly what is missing before it is computed. `from` is inclusive and `to` is EXCLUSIVE — for whole months, pass the first day of the month after the last one you want. **These rows are measured on when the movement happened (`executed_at`), not on its accounting date.** That is deliberate and it matters: the two disagree about which MONTH a transaction belongs to for a large share of real data, and many rows carry no accounting date at all. A caller listing rows on one basis while summing a figure on the other ends up with rows it counts but cannot offer to fix. Pair this with a sum measured on the same basis. Returns each row's identity, amount, counterparty and the classifier's pending suggestion where one exists. It lists rows with NO category; a categorized row that has not yet posted to the ledger is a booking question and is not returned here. `meta.truncated: true` means the page filled and more rows exist, so report the count as a floor rather than as the total. `meta.returned` is what came back. **`success: false` means the window is UNKNOWN, not empty.** The read failed, so no count exists and `returned` and `truncated` are absent rather than zero. An empty `records` on a failed read is not "nothing is uncategorized" — treating it that way reports a clean list this read never produced. Say the list could not be read. Do not propose categories from this list. Where the classifier has a proposal it rides on the row, and the assignment surface is where a category is chosen. When the user asks to see, list or fix these rows, call this tool directly: its card is the answer. ⚠️ **This tool draws its card on EVERY call, the empty one included.** So when nobody asked for the list and you only need to CHECK whether anything is left (the first pass of a gate, or a re-check after a repair), call `well_get_worklist_status({ worklist: "uncategorized_window", from, to })` first, with the same scope you would pass here. It draws nothing. Call this tool after it only when it answers `open: true`. When the token authorizes one workspace, call this directly — no other tool call is needed first. When it authorizes several, this read will not guess which one you mean: pass `workspace_id` on the call.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['from', 'to'], 'properties': {'to': {'type': 'string', 'description': 'EXCLUSIVE end of the window, YYYY-MM-DD.'}, 'from': {'type': 'string', 'description': 'Inclusive start of the window, YYYY-MM-DD.'}, 'limit': {'type': 'integer', 'maximum': 500, 'minimum': 1, 'description': 'Max rows to return (default 500).'}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which."}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['records', 'window', 'success'], 'properties': {'error': {'type': 'string'}, 'window': {'type': 'object', 'required': ['from', 'to'], 'properties': {'to': {'type': 'string'}, 'from': {'type': 'string'}}, 'additionalProperties': False}, 'records': {'type': 'array', 'items': {'type': 'object', 'propertyNames': {'type': 'string'}, 'additionalProperties': {}}}, 'success': {'type': 'boolean'}, 'returned': {'type': 'number'}, 'truncated': {'type': 'boolean'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_list_unposted_journals

List journals still to post

List the transactions AND invoices of a fiscal period whose journal entry a posting retry can still clear on its own — the re-triggerable posting gap. An empty list with `scan_truncated: false` means no re-triggerable row remains in the rows scanned. That is NOT proof the period is posted: this read omits rows halted on a substantive reason a repost cannot clear (a missing ledger account, a tax gate, a locked period), so never declare the period posted on an empty read alone. If the close still reports an unposted blocker for this period, those rows need an accounting decision, not a re-trigger. This is NOT the categorization surface. For a row that still needs a category or a ledger account, use `well_list_unposted_transactions`. This read carries only the rows that are ready to post and simply have not yet: the posting pipeline did not run. It never lists a row halted on a substantive reason (a missing ledger account, a tax gate, a locked period) — a retry only re-fails those, and the categorization and hydration steps own them. Each row carries `source_id`, `source_kind` (`transaction` or `invoice`), `name` (the counterparty composite), `amount`, and `period_date`. **`in_flight_processing: true` means Well is still processing these rows — enrichment (classification, matching, re-extraction) is in flight, so wait and re-read rather than reposting.** Re-read on the close's wait cadence until it is false; only then is the (i)-set settled enough to re-trigger. The paired write is `well_repost_journals`. **`scan_truncated: true` means the (i)-set was read from a bounded slice of the workspace's rows, not all of them.** An empty list under this flag means "no re-triggerable row was found in the rows scanned", NOT "every row is posted" — do not tell the user the close can skip this step on a truncated empty read. The period is named in FISCAL terms, and a workspace's fiscal calendar need not follow the calendar year. Take `fiscal_year` and `fiscal_period` from a `well_list_periods` entry, or from the months the user already selected this session; never derive them from a calendar month yourself. **`success: false` means the period is UNKNOWN, not clear.** The read failed, so no count exists, and an empty `records` on a failed read is not "everything posted". When the token authorizes one workspace, call this directly — no other tool call is needed first. When it authorizes several, this read will not guess which one you mean: pass `workspace_id` on the call.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['fiscal_year', 'fiscal_period'], 'properties': {'limit': {'type': 'integer', 'maximum': 500, 'minimum': 1, 'description': 'Max rows to return.'}, 'fiscal_year': {'type': 'integer', 'maximum': 2100, 'minimum': 2000, 'description': 'The fiscal year of the period to read.'}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which."}, 'fiscal_period': {'type': 'integer', 'maximum': 13, 'minimum': 1, 'description': 'The fiscal period, 1-12 for a month; 13 is the adjustment period and resolves to no rows.'}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['records', 'in_flight_processing', 'scan_truncated', 'success'], 'properties': {'error': {'type': 'string'}, 'records': {'type': 'array', 'items': {'type': 'object', 'propertyNames': {'type': 'string'}, 'additionalProperties': {}}}, 'success': {'type': 'boolean'}, 'returned': {'type': 'number'}, 'scan_truncated': {'type': 'boolean'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'in_flight_processing': {'type': 'boolean'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_list_unposted_transactions

List transactions still to post

List the transactions of a fiscal period that carry a category or a role and have STILL not reached the ledger, so a close can say exactly what is holding it. This is the posting gap, not the categorization gap. A row here already has a category; what it lacks is the ledger account its journal entry would post to. For rows carrying no category at all, use `well_list_uncategorized_window`. Each row carries `transaction_id`, `label`, `amount`, `period_date`, the `current_ledger` already attached where one is, and `ledger_suggestions` — the classifier's proposals, each with the account's `code` (its number, e.g. "6156") beside its name. The `ledger_catalog.accounts` list carries every account this workspace can post to, with the id `well_set_transaction_ledger_account` takes. A row whose `ledger_suggestions` is empty is assigned from that list: the classifier proposed nothing, which is not the same as the row having nowhere to go. **The rows arrive snake_cased** (`period_date`, `ledger_suggestions`, `current_ledger`), unlike `well_list_uncategorized_window`, whose close cousin emits camelCase. A caller reading one shape against the other silently sees empty fields rather than an error. The period is named in FISCAL terms, and a workspace's fiscal calendar need not follow the calendar year: "June 2026" is not reliably fiscal period 6. Take `fiscal_year` and `fiscal_period` from a `well_list_periods` entry, or from the months the user already selected in this conversation; never derive them from a calendar month yourself. Most categories already determine their ledger account: the chart maps each category key to a canonical code, and only a handful abstain because the category alone cannot pick a safe account without the transaction direction. So a long list here usually means the categories are missing, not the accounts. **`success: false` means the period is UNKNOWN, not clear.** The read failed, so no count exists, and an empty `records` on a failed read is not "everything posted". `truncated: true` means the period holds MORE unposted rows than this page carries, so `returned` is a floor rather than the period's total. Narrow the period, or state the count as "at least". When the user asks to see, list or fix these rows, call this tool directly: its card is the answer. ⚠️ **This tool draws its card on EVERY call, the empty one included.** So when nobody asked for the list and you only need to CHECK whether anything is left (the first pass of a gate, or a re-check after a repair), call `well_get_worklist_status({ worklist: "unposted_transactions", fiscal_year, fiscal_period })` first, with the same scope you would pass here. It draws nothing. Call this tool after it only when it answers `open: true`. When the token authorizes one workspace, call this directly — no other tool call is needed first. When it authorizes several, this read will not guess which one you mean: pass `workspace_id` on the call.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['fiscal_year', 'fiscal_period'], 'properties': {'limit': {'type': 'integer', 'maximum': 500, 'minimum': 1, 'description': 'Max rows to return.'}, 'fiscal_year': {'type': 'integer', 'maximum': 2100, 'minimum': 2000, 'description': 'The fiscal year of the period to read.'}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which."}, 'fiscal_period': {'type': 'integer', 'maximum': 13, 'minimum': 1, 'description': 'The fiscal period, 1-12 for a month; 13 is the adjustment period and resolves to no rows.'}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['records', 'success'], 'properties': {'error': {'type': 'string'}, 'records': {'type': 'array', 'items': {'type': 'object', 'propertyNames': {'type': 'string'}, 'additionalProperties': {}}}, 'success': {'type': 'boolean'}, 'returned': {'type': 'number'}, 'truncated': {'type': 'boolean'}, 'ledger_catalog': {'type': 'object', 'required': ['accounts', 'returned', 'truncated', 'failed'], 'properties': {'failed': {'type': 'boolean'}, 'accounts': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'name'], 'properties': {'id': {'type': 'string'}, 'code': {'type': 'string'}, 'name': {'type': 'string'}}, 'additionalProperties': False}}, 'returned': {'type': 'number'}, 'truncated': {'type': 'boolean'}}, 'additionalProperties': False}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_list_workspaces

List workspaces

List the workspaces this connection is authorized to access. This draws nothing on the user's screen. Use this FIRST when a single token may cover more than one workspace, and use it for every case a caller can settle on its OWN: exactly one workspace, a hint that matches one, a pin this conversation already wrote, or none at all. Read the rows and say which workspace you took. ⚠️ TO ASK THE USER WHICH WORKSPACE, CALL `well_show_workspace_picker` INSTEAD. It draws one tile per workspace and waits for a click. Reach for it only when the token authorizes several AND no hint resolves — a chooser over a set of one asks nothing, and a chooser the caller could have answered itself asks a question it already knows the answer to. 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). - own_company_id: the public id of the company this workspace is anchored to, or null. A row that carries it is a company workspace: the close flow runs in one. A row without it is a membership workspace, the container a sign-up mints. - lineage_parent_workspace_id: the workspace_id of the membership this workspace was created under, or null when the workspace has no active lineage. A membership workspace (no own_company_id) whose id appears here on other rows is the parent of those company workspaces. - identity: the company behind the workspace (registered name, trade name, registry number, country, website, currency, fiscal year start, where the fiscal year start came from, and the jurisdiction's default fiscal year start), so two similarly-named workspaces can be told apart. Every field is null when the workspace has no accounting settings yet. Tax identifiers are deliberately not included. - has_bank_transactions: whether a connector the workspace BANKS with has delivered any transaction to it, meaning a bank, a neobank, or a treasury or spend platform whose product is an account. An accounting platform and a payment processor deliver transactions too and do NOT count here. Neither does a transaction whose source connector is unknown, whose install has since been disconnected, or whose catalog entry has been retired. Only `true` shows that a bank has fed this workspace: `false` means no such transaction was found and `null` means the signal could not be read, so an absent value is never a zero and neither value licenses skipping a bank-connection step. Read this before any month read when the flow needs to know whether the workspace banks with anything at all. The result also carries `session`, what the user's card clicks have already recorded in this conversation: `pinned_workspace_id` (null when not switched), `workspace_queue` (the workspaces to work through next, empty when none), `selected_periods` (the months picked on the period card, empty when none), and `selected_counterparties` (the counterparties picked on the missing-invoices card, with the workspace their company ids belong to; null when none was picked). Call this any time you need to resync with clicks you may have missed. 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. ⚠️ A row without `own_company_id` is a membership workspace with no company of its own. TO ASK THE USER WHICH COMPANY that workspace IS — to show its detected company candidates and let them pick — CALL `well_show_company_candidates`, never this read: this list never shows the candidates.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Optional: this tool describes the token itself rather than one workspace's data, so omitting it returns the same answer."}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['workspaces', 'success'], 'properties': {'error': {'type': 'string'}, 'session': {'type': 'object', 'required': ['pinned_workspace_id', 'workspace_queue', 'selected_periods', 'selected_counterparties'], 'properties': {'workspace_queue': {'type': 'array', 'items': {'type': 'string'}}, 'selected_periods': {'type': 'array', 'items': {'type': 'object', 'required': ['calendar_year', 'calendar_month'], 'properties': {'calendar_year': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'calendar_month': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}}, 'additionalProperties': False}}, 'pinned_workspace_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'selected_counterparties': {'anyOf': [{'type': 'object', 'required': ['workspace_id', 'counterparties'], 'properties': {'workspace_id': {'type': 'string', 'description': 'The workspace the picked company ids belong to.'}, 'counterparties': {'type': 'array', 'items': {'type': 'object', 'required': ['company_id', 'matched_connector_service_id'], 'properties': {'company_id': {'type': 'string'}, 'matched_connector_service_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "The connector that can fetch this counterparty's invoices; null when none matched."}}, 'additionalProperties': False}}}, 'additionalProperties': False}, {'type': 'null'}], 'description': 'The counterparties picked on the missing-invoices card; null until a pick is recorded.'}}, 'description': "What this conversation's card clicks recorded so far; null/empty fields when nothing was clicked yet.", 'additionalProperties': False}, 'success': {'type': 'boolean'}, 'workspaces': {'type': 'array', 'items': {'type': 'object', 'required': ['workspace_id', 'workspace_name', 'is_primary', 'own_company_id', 'lineage_parent_workspace_id', 'has_bank_transactions', 'identity'], 'properties': {'identity': {'type': 'object', 'required': ['registered_name', 'trade_name', 'registered_value', 'country', 'domain', 'base_currency', 'fiscal_year_start_month', 'fiscal_year_start_month_source', 'country_default_fiscal_year_start_month'], 'properties': {'domain': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'country': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'trade_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'base_currency': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'registered_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'registered_value': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'fiscal_year_start_month': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'fiscal_year_start_month_source': {'anyOf': [{'enum': ['derived', 'registry', 'user'], 'type': 'string'}, {'type': 'null'}], 'description': 'Where fiscal_year_start_month came from: "registry" from a company registry, "derived" from the country fallback, "user" from a human. Null when never set. Tells a confirmed fiscal year from one resting on a default.'}, 'country_default_fiscal_year_start_month': {'anyOf': [{'type': 'number'}, {'type': 'null'}], 'description': "The jurisdiction's default fiscal-year-start month for this country, or null when the country has no single confident default (non-null for France only today)."}}, 'additionalProperties': False}, 'is_primary': {'type': 'boolean'}, 'workspace_id': {'type': 'string'}, 'own_company_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': 'The public id of the company this workspace is anchored to, or null. A row that carries it is a company workspace, the one the close flow runs in; a row without it is a membership workspace.'}, 'workspace_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'has_bank_transactions': {'anyOf': [{'type': 'boolean'}, {'type': 'null'}], 'description': 'Whether a connector the workspace BANKS with has delivered any transaction to it: a bank, a neobank, or a treasury or spend platform whose product is an account. An accounting platform and a payment processor deliver transactions too and do NOT count. A transaction whose source connector is unknown, whose install has since been disconnected, or whose catalog entry has been retired does not count either. Only true shows a bank has fed this workspace. false means no such transaction was found; null means the signal could not be read. An absent value is not a zero, and neither false nor null licenses skipping a bank-connection step.'}, 'lineage_parent_workspace_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "The workspace_id of the membership this workspace was created under, or null when it has no active lineage. Its parent's own row is the membership whose id this points at."}}, 'additionalProperties': False}}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_preview_invoice_fetch

Preview invoice fetch

Preview which vendors a past period is still missing supplier invoices from, where each one's invoices are, and which route would obtain them. Use it for "what would happen if I fetched <month>'s missing invoices?" before anything runs. Name the period ONE way: `{ calendar_year, calendar_month }` (the calendar month, e.g. June 2026 → 2026, 6), `{ fiscal_year, fiscal_period }`, or `periods: [{ calendar_year, calendar_month }, …]` for SEVERAL months in one call (1-12), or name NO period at all to use the months the user selected on the period card in this conversation (well_list_periods → the user clicks → well_switch_workspace records them). With no period named and no months selected, the call refuses and tells you to run the period step first. Every month must have ended: a current or future month is refused, and so is the adjustment period (13). Duplicate months are refused. COST: there is no batch endpoint, so each named month is a separate read of that month's spend. Ask for the months the user actually named, not a whole year "to be safe". Returns `vendors` — EVERY vendor of the rows THIS CALL covers, one entry per supplier portal ACROSS the whole window (one portal is one place to go, however many months it spans), or one per counterparty where no portal matched: `name`, `provider_id`, `domain`, `url` and `url_source`, the `counterparties` it covers (each tagged with `calendar_year`, `calendar_month`, `period_label` and `suggested_route`), `tx_count`, `base_total_amount` in `base_currency`. THE ROUTE NEVER FILTERS `vendors`: a vendor Well has no published flow and no connector for is listed exactly like the rest, with its route on its counterparties. WHAT the call covers is a separate question, and two fields answer it: a counterparty pick narrows the rows to the picked companies (see `scoped_to_selected_counterparties` below), and a `hints` line names any group the projection could produce no vendor for. So `vendors` is every vendor of the rows THIS CALL covers, which is the whole period only when neither of those is present. `upload_rows` (the user must supply the file) and `connect_rows` (connecting the named service fetches it) carry the same counterparties again, split by route, with the same month tags. WHERE A VENDOR'S INVOICES ARE: `url_source` says how much `url` knows. "blueprint" is the page Well's own published flow opens, so it IS the billing page. "enrichment" is the vendor's front door — the catalog entry address or the company's domain — so the user still has to find the invoices on it. "none" means no address at all and `url` is null. Never present an "enrichment" address as the invoice page. `url_source` informs and gates nothing: an "enrichment" vendor is offered for the pick, and carried on the link, exactly like a "blueprint" one. ROUTES DESCRIBE HOW, NOT WHETHER: a counterparty Well holds a connector for is in `connect_rows` AND under its vendor, where its entry reads `suggested_route: "connect"` and `connect_routed_counterparties` counts it. Connecting is the route to suggest; the agent run stays available so the user has a way through when the connector does not work for them. A counterparty on `suggested_route: "upload"` is in `upload_rows` too. Never present the same counterparty as two separate gaps — it is one gap seen twice, so count it once. `counts` covers the rows this call actually read, and every field states its own unit: `vendors` and `agents` count PORTALS, `agent_tx` counts TRANSACTIONS, `upload` and `connect` count COUNTERPARTY ROWS — one counterparty per month. They are not summable with each other: never add them into one total, and `vendors` is never the sum of the other four, because every counterparty reaches the vendor list whichever route it takes. A total over the whole window counts the DISTINCT counterparties named in `vendors`, and a counterparty appearing again in `upload_rows` or `connect_rows` is the same gap seen by its route. Across several months a counterparty counts once per month in `upload` and `connect`, while `vendors` and `agents` count each portal once for the window, so neither is the sum of the months' own. WHEN `scoped_to_selected_counterparties` IS PRESENT, `vendors`, `upload_rows`, `connect_rows`, `counts` AND `months` COVER ONLY THE PICKED COUNTERPARTIES, NOT THE WHOLE WINDOW: for the months the pick bounded, every row and every figure here is built from the picked rows alone, and `selection_scope` says how many counterparty rows it left out. Never report those rows as every vendor the period is missing an invoice from, and never report those counts as the period's own — state the truncation and its size, and point at `well_list_missing_invoices` for a fresh card that drops the pick. Without that field the counts cover the whole window. `months` gives each month's own counts; `periods_covered` names the months. A sum is `null` when any member of it had no FX rate, never a partial figure. The single-month fields `calendar_year`, `calendar_month`, `fiscal_year`, `fiscal_period` and `period_label` appear ONLY when the call named exactly one month. THIS TOOL LAUNCHES NOTHING. It creates no task, starts no run, and fetches no invoice — `mode` is always `"preview"` and `nothing_launched` is always `true`. Launching the agents is NOT available on this surface, so present the preview as information and do not promise to run it. `collect_url` is the ONE link to hand the user: the `/collect` page, which asks the Well browser extension to run these portals. It names each portal by its `provider_id`, and that id is the only field that decides which portal runs — a name or an address in the link labels a row and nothing more. Give the link as returned and never build one or edit its parameters. The page starts nothing until the user acts on it, it reports which portals the extension accepted, and it never reports that an invoice arrived. The link also names this workspace, and that name gates WHO may act on the link: the page starts nothing until the reader is signed in to Well as a member of it. It does NOT choose where the invoices land — the extension files into whichever workspace it is signed in to — so never tell the user the link picks the destination. THE LINK CARRIES EVERY VENDOR THAT HAS AN ADDRESS, whatever its `url_source` and whether or not Well holds a published flow for it. Deciding what a vendor's invoices need once the page opens belongs to the app and the extension, not to this read, so `url_source` labels a vendor and never withholds it. Two things still keep a vendor off the link: no address at all, and no `provider_id` the link can address. `collect_url` is null when the window holds no addressed vendor at all; `collect_url_omits` names the vendors a full window pushed past the 25-portal ceiling, and `collect_url_unaddressable` names the ones the link cannot name. A vendor on either list is still missing its invoice, so say the link cannot carry it, and offer the upload or the connect route from `upload_rows` and `connect_rows` instead. Never say it has nothing outstanding. Only CATEGORIZED expense transactions are considered — uncategorized spend is not counted, so poor categorization coverage under-reports what an agent run would cover; disclose the `hints`. Call this directly — no other tool call is needed first (workspace is resolved from the caller's authorized token, same as every other well_* tool).

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'periods': {'type': 'array', 'items': {'type': 'object', 'required': ['calendar_year', 'calendar_month'], 'properties': {'calendar_year': {'type': 'integer', 'maximum': 2100, 'minimum': 2000, 'description': 'Calendar year, e.g. 2026.'}, 'calendar_month': {'type': 'integer', 'maximum': 12, 'minimum': 1, 'description': 'Calendar month, 1 = January … 12 = December.'}}, 'additionalProperties': False}, 'maxItems': 12, 'minItems': 1, 'description': 'Several calendar months in one call, 1-12. Each month costs one separate read, so name only the months you need. Duplicates are refused.'}, 'fiscal_year': {'type': 'integer', 'maximum': 2100, 'minimum': 2000, 'description': "Fiscal year (the calendar year the workspace's fiscal year STARTED in)."}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. This read reports one workspace's own data. Omit it and the token's primary workspace answers, which may not be the one you mean; the result names the workspace that did."}, 'calendar_year': {'type': 'integer', 'maximum': 2100, 'minimum': 2000, 'description': 'Calendar year, e.g. 2026.'}, 'fiscal_period': {'type': 'integer', 'maximum': 13, 'minimum': 1, 'description': 'Fiscal period, 1-12. The adjustment period (13) is refused: it has no calendar month.'}, 'calendar_month': {'type': 'integer', 'maximum': 12, 'minimum': 1, 'description': 'Calendar month, 1 = January … 12 = December.'}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['vendors', 'upload_rows', 'connect_rows', 'success'], 'properties': {'mode': {'type': 'string', 'const': 'preview'}, 'error': {'type': 'string'}, 'hints': {'type': 'array', 'items': {'type': 'string'}}, 'counts': {'type': 'object', 'required': ['vendors', 'agents', 'agent_tx', 'upload', 'connect'], 'properties': {'agents': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': "Portals Well holds a published flow for, one per distinct provider, the connector-covered ones included. It marks the shorter route and is NOT the link's own set: `collect_url` names every addressed vendor it can name by id, so it routinely carries portals this count leaves out."}, 'upload': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Counterparties whose invoice only a manual upload can obtain.'}, 'connect': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Counterparties whose suggested route is connecting a service.'}, 'vendors': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Vendors the card lists — one per distinct portal, or per counterparty where none matched.'}, 'agent_tx': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Transactions those agent runs would fetch.'}}, 'description': "The whole window's counts. `vendors` and `agents` count the distinct portals across it, so neither is the sum of the months' own. `upload` and `connect` add each month's counterparty rows, so a counterparty missing an invoice in two of the months read counts once per month.", 'additionalProperties': False}, 'months': {'type': 'array', 'items': {'type': 'object', 'required': ['calendar_year', 'calendar_month', 'period_label', 'fiscal_year', 'fiscal_period', 'counts'], 'properties': {'counts': {'type': 'object', 'required': ['vendors', 'agents', 'agent_tx', 'upload', 'connect'], 'properties': {'agents': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': "Portals Well holds a published flow for, one per distinct provider, the connector-covered ones included. It marks the shorter route and is NOT the link's own set: `collect_url` names every addressed vendor it can name by id, so it routinely carries portals this count leaves out."}, 'upload': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Counterparties whose invoice only a manual upload can obtain.'}, 'connect': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Counterparties whose suggested route is connecting a service.'}, 'vendors': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Vendors the card lists — one per distinct portal, or per counterparty where none matched.'}, 'agent_tx': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Transactions those agent runs would fetch.'}}, 'additionalProperties': False}, 'fiscal_year': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'period_label': {'type': 'string'}, 'calendar_year': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'fiscal_period': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'calendar_month': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}}, 'additionalProperties': False}, 'description': 'Per-month route counts, oldest first.'}, 'success': {'type': 'boolean'}, 'vendors': {'type': 'array', 'items': {'type': 'object', 'required': ['key', 'name', 'provider_id', 'domain', 'url', 'url_source', 'logo_url', 'counterparties', 'connect_routed_counterparties', 'tx_count', 'base_total_amount'], 'properties': {'key': {'type': 'string', 'description': 'Stable identity for this entry across a re-read: the portal when one matched, else the counterparty row. Two vendors sharing a display name have different keys, so key rows on this and never on `name`.'}, 'url': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': 'Where this vendor\'s invoices are, e.g. "https://www.dropbox.com/manage/billing". `url_source` says how close that address stands to the invoices. Null only when `url_source` is "none". An address is what makes a vendor offerable at all: a vendor carrying one is offered for the pick, and with a `provider_id` it is also named on `collect_url`, whatever its `url_source`. The address itself never travels, because the id is the only field the extension acts on.'}, 'name': {'type': 'string', 'description': "The vendor as the card names it: the matched provider's name, or the counterparty's own when none matched."}, 'domain': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': 'The vendor\'s own bare host, e.g. "aws.amazon.com" — the catalog provider\'s host, or the counterparty company\'s. It identifies the vendor and its mark; it is NOT `url` reduced, because `url` may point deeper into the portal.'}, 'logo_url': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "The provider's logo as Well stores it. Null when the provider is unmatched or Well holds no stored mark for it, in which case the card still renders one from `domain`."}, 'tx_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Transactions still missing an invoice, over every counterparty listed above.'}, 'url_source': {'enum': ['blueprint', 'enrichment', 'none'], 'type': 'string', 'description': 'Where `url` came from. "blueprint" — the provider\'s published flow, so it opens the billing page itself. "enrichment" — the catalog\'s entry address or the company\'s own domain, so it is the vendor\'s front door and the user still has to find the invoices on it. "none" — no address at all, and `url` is null. It says where the address came from and gates nothing: an "enrichment" vendor is offered, and carried on the link, exactly like a "blueprint" one.'}, 'provider_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "The catalog id, and the only field that can put this vendor on `collect_url`. Necessary but NOT sufficient: the link also needs the vendor to carry a `url`, and the vendor has to fit the link's own ceiling. Null when no provider matched. A vendor off the link is still listed and is still offered for the pick, so report it as one the link cannot carry, never as one Well leaves out."}, 'counterparties': {'type': 'array', 'items': {'type': 'object', 'required': ['name', 'calendar_year', 'calendar_month', 'period_label', 'tx_count', 'base_total_amount', 'suggested_route'], 'properties': {'name': {'type': 'string'}, 'tx_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'period_label': {'type': 'string', 'description': 'The month this row belongs to, e.g. "June 2026".'}, 'calendar_year': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'calendar_month': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'suggested_route': {'enum': ['agent', 'connect', 'upload'], 'type': 'string', 'description': '"agent" when the agent run is the suggested route. "connect" when a Well connector is suggested instead — the counterparty is ALSO in `connect_rows`. "upload" when Well holds neither a connector nor a published flow for it — the counterparty is ALSO in `upload_rows`.'}, 'base_total_amount': {'anyOf': [{'type': 'number'}, {'type': 'null'}], 'description': 'Sum in base_currency; null when an FX rate was missing for any transaction in the sum.'}}, 'additionalProperties': False}, 'description': 'The counterparties this one vendor covers, each tagged with the month it belongs to and with the route the preview suggests for it.'}, 'base_total_amount': {'anyOf': [{'type': 'number'}, {'type': 'null'}], 'description': 'Sum in base_currency; null when an FX rate was missing for any transaction in the sum.'}, 'connect_routed_counterparties': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'How many of `counterparties` the preview suggests connecting instead. They are counted in `tx_count` and `base_total_amount`, and they are ALSO in `connect_rows`, where they are counted as connect counterparties.'}}, 'additionalProperties': False}, 'description': 'EVERY vendor of the rows THIS CALL covers, whatever route its invoice would arrive by — one entry per supplier portal across the whole window, or per counterparty where no portal matched. The ROUTE never filters this list: a vendor Well has no published flow and no connector for is listed exactly like the rest. What the call covers can still be narrower than the period, and the envelope says so: when `scoped_to_selected_counterparties` is present these are the picked counterparties alone and `selection_scope` sizes the remainder, and a `hints` line names any group the projection could produce no vendor for.'}, 'next_step': {'type': 'string', 'description': 'What to do with the card this result renders. Added by the dispatcher when the card asks for a click.'}, 'collect_url': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "The `/collect` entry that hands these vendors to the Well browser extension, naming each one by its `provider_id` and naming this workspace as the link's authorization scope. The page starts nothing until the reader is signed in to Well as a member of it. It carries every vendor that has an address, whatever that address's `url_source`, because what a vendor's invoices need once the page opens is the app's and the extension's decision rather than this read's. Null in three unrelated cases: no vendor of the window carries an address, none of the addressed vendors carries an id the link can address, or this read could not name the workspace the link authorizes. The hints name which one, and only the first is a verdict on the vendors. Opening it starts nothing on its own: the user acts on the page."}, 'fiscal_year': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Present only when the call named exactly one month.'}, 'upload_rows': {'type': 'array', 'items': {'type': 'object', 'required': ['name', 'calendar_year', 'calendar_month', 'period_label', 'tx_count', 'base_total_amount'], 'properties': {'name': {'type': 'string'}, 'tx_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'period_label': {'type': 'string', 'description': 'The month this row belongs to, e.g. "June 2026".'}, 'calendar_year': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'calendar_month': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'base_total_amount': {'anyOf': [{'type': 'number'}, {'type': 'null'}], 'description': 'Sum in base_currency; null when an FX rate was missing for any transaction in the sum.'}}, 'additionalProperties': False}, 'description': 'Counterparties whose invoice only a manual upload can obtain.'}, 'connect_rows': {'type': 'array', 'items': {'type': 'object', 'required': ['name', 'calendar_year', 'calendar_month', 'period_label', 'tx_count', 'base_total_amount', 'matched_provider_name'], 'properties': {'name': {'type': 'string'}, 'tx_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'period_label': {'type': 'string', 'description': 'The month this row belongs to, e.g. "June 2026".'}, 'calendar_year': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'calendar_month': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'base_total_amount': {'anyOf': [{'type': 'number'}, {'type': 'null'}], 'description': 'Sum in base_currency; null when an FX rate was missing for any transaction in the sum.'}, 'matched_provider_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': 'The service to connect, when the read matched one.'}}, 'additionalProperties': False}, 'description': 'Counterparties whose invoice arrives by connecting a service.'}, 'period_label': {'type': 'string', 'description': 'Human-readable label of the period, e.g. "June 2026". Present only when the call named one month.'}, 'workspace_id': {'type': 'string'}, 'base_currency': {'type': 'string'}, 'calendar_year': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Present only when the call named exactly one month.'}, 'fiscal_period': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Present only when the call named exactly one month.'}, 'calendar_month': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Present only when the call named exactly one month.'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'periods_covered': {'type': 'array', 'items': {'type': 'object', 'required': ['calendar_year', 'calendar_month', 'period_label'], 'properties': {'period_label': {'type': 'string', 'description': 'The month this row belongs to, e.g. "June 2026".'}, 'calendar_year': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'calendar_month': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}}, 'additionalProperties': False}, 'description': 'The months the result covers, oldest first.'}, 'selection_scope': {'type': 'object', 'required': ['row_count_before_filter', 'rows_dropped_by_filter'], 'properties': {'rows_dropped_by_filter': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'How many of those rows the pick left out — gaps the routes and the counts below do not cover.'}, 'row_count_before_filter': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Counterparty rows the months read hold in total, before the pick narrowed them. Includes the months the pick does not bound, which are reported in full.'}}, 'description': 'What the pick removed. Present with `scoped_to_selected_counterparties`, so the size of the truncation is readable beside the result.', 'additionalProperties': False}, 'nothing_launched': {'type': 'boolean', 'const': True, 'description': 'Always true — this tool never starts anything.'}, 'collect_url_omits': {'type': 'array', 'items': {'type': 'object', 'required': ['provider_id', 'provider_name'], 'properties': {'provider_id': {'type': 'string'}, 'provider_name': {'type': 'string'}}, 'additionalProperties': False}, 'description': 'The portals `collect_url` does NOT name, because one link carries at most 25. Present only when the ceiling left some out. Report those vendors as outside the link — it starts nothing for them.'}, 'periods_requested': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'How many calendar months the call named.'}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}, 'collect_url_unaddressable': {'type': 'array', 'items': {'type': 'object', 'required': ['name'], 'properties': {'name': {'type': 'string'}}, 'additionalProperties': False}, 'description': 'The vendors `collect_url` does not name: the vendor carries no address at all, or it carries one but no catalog id the link can address. A missing published flow is NOT among the reasons, because the link takes an enrichment address exactly like a blueprint one. Present only when the window holds some. They are real gaps and they are listed in `vendors`; report them as vendors the link cannot carry, never as absent.'}, 'rows_dropped_by_ownership': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': "Counterparty rows this preview dropped because the current user owns none of their gaps — a fetch runs as the current user and can only collect the invoices of counterparties they own. Counted apart from `selection_scope.rows_dropped_by_filter` (the pick's own shortfall), and present only when it dropped at least one. The matching `hints` line names it."}, 'scoped_to_selected_counterparties': {'type': 'boolean', 'const': True, 'description': 'Present when a counterparty pick narrowed this preview: for the months the pick was made against, every route below covers only those companies. A month outside the pick is covered in full.'}}, 'additionalProperties': False}

well_propose_next_steps

Propose next steps

Put five next steps on a card, as five lines the person can send. **This tool ranks nothing.** The five skills and their order come from well_get_session_digest's `suggested_steps`; pass them in that order. The sentence beside each one is yours to write, in the language the person is using, from that skill's own quoted utterances and the figures the digest returned. When that list is empty or shorter than five, do NOT call this tool and do not write five of your own: say in one line that the next steps cannot be proposed this time. The server checks that each line can travel and hands the list to the card. Call it at the END of a skill that tells you to, never to work out what the person should do. Each step is a pair: - `skill` the slug of a Well skill, exactly as well_search_skill lists it. A slug the catalog does not hold is refused, and the refusal names the slugs it does. - `prompt` one natural sentence, 1 to 160 characters, written from that skill's own quoted trigger utterances. Write what the PERSON would say, in their words, not an instruction to yourself. REFUSED rather than rendered: - a step naming a brick a flow invokes (`define-workspace`, `define-period`, `normalize-currency`) or one of the two skills that call this tool (`signing-back`, `whats-next`): nobody sends those, so rank another skill in its place - a prompt that starts with "/": the host reads it as a command, not as a message - a prompt containing "<": the host can read it as markup - a prompt containing a line break: a row carries one line - fewer or more than 5 steps: the card is a fixed list Clicking a line records that pick on this connection. Read it back with well_wait_for_selection({ kind: "next_step", timeout_s: 60 }) in this same turn: on "selected", take selection.next_step.prompt as the person's own message and start selection.next_step.skill at once, loading it with well_get_skill. When no turn is waiting, the card sends the sentence into the conversation itself as the person's own message. That is the recovery, not the plan: it arrives as a fresh turn that starts from nothing you already hold. Every row stays clickable while the card is on screen, and a click changes nothing about the row: a person who takes a second step later finds the same five lines. When the card renders, the five lines are already in front of the person and the card sits where this call sits in the turn: write everything you have to say BEFORE calling. After it, the only thing that follows is the well_wait_for_selection call the result's `next_step` field spells out. Prose in place of that call ends the turn, and the click then has to restart the work from a new message rather than continue this one.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['steps'], 'properties': {'steps': {'type': 'array', 'items': {'type': 'object', 'required': ['skill', 'prompt'], 'properties': {'skill': {'type': 'string', 'pattern': '^[a-z0-9-]{1,64}$', 'description': 'The id of the skill this step offers, as well_search_skill lists it.'}, 'prompt': {'type': 'string', 'maxLength': 160, 'minLength': 1, 'description': 'One sentence the person can send as is, written from the skill\'s own quoted trigger utterances. Refused when it starts with "/", contains "<", or contains a line break.'}}, 'additionalProperties': False}, 'maxItems': 5, 'minItems': 5, 'description': 'Exactly 5 steps, in the order the card lists them.'}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Optional: this tool describes the token itself rather than one workspace's data, so omitting it returns the same answer."}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success', 'reason', 'steps', 'hint'], 'properties': {'hint': {'type': 'string'}, 'error': {'type': 'string'}, 'steps': {'type': 'array', 'items': {'type': 'object', 'required': ['skill', 'prompt'], 'properties': {'skill': {'type': 'string'}, 'prompt': {'type': 'string'}}, 'additionalProperties': False}}, 'reason': {'anyOf': [{'enum': ['skill_unknown', 'skill_not_proposable', 'prompt_invalid', 'catalog_unreadable', 'unexpected'], 'type': 'string'}, {'type': 'null'}]}, 'success': {'type': 'boolean'}, 'next_step': {'type': 'string', 'description': 'What to do with the card this result renders. Added by the dispatcher when the card asks for a click.'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_query_records

Query records

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 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: - `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"] - 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 is still owed on the unpaid invoices?": well_query_records({ root: "invoices", fields: [["invoices", "balance_due"]], whereClause: { "payment_status": { "_in": ["unpaid", "partial"] } } }) // balance_due arrives in the rows for you to total up. 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 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 }.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['root'], 'properties': {'root': {'type': 'string', 'description': '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.'}, 'limit': {'type': 'number', 'maximum': 500, 'minimum': 1, 'description': 'Max records to return (default 50, max 500)'}, 'cursor': {'type': 'string', 'description': 'Opaque cursor for the next page. Omit for the first page, then pass nextCursor from the previous response.'}, 'fields': {'type': 'array', 'items': {'type': 'array', 'items': {'type': 'string'}}, 'description': "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."}, 'orderBy': {'type': 'object', 'required': ['field', 'direction'], 'properties': {'field': {'type': 'string', 'description': 'Field name to sort by'}, 'direction': {'enum': ['asc', 'desc'], 'type': 'string', 'description': 'Sort direction'}}, 'description': 'Sort results by a field. Example: { field: "grand_total", direction: "desc" }'}, 'allFields': {'type': 'boolean', 'description': 'If true, automatically fetches all scalar fields from schema. No need to specify fields.'}, 'partyScope': {'enum': ['purchase', 'sales', 'intra_self', 'unattributed'], 'type': 'string', '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.'}, 'whereClause': {'type': 'object', 'description': 'Hasura-style filter object. Operators: _eq, _neq, _gt, _gte, _lt, _lte, _like, _ilike, _in, _nin, _is_null. Example: { "status": { "_eq": "unpaid" } }', 'propertyNames': {'type': 'string'}, 'additionalProperties': {}}, 'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit to query every authorized workspace at once; each row comes back tagged with the workspace it belongs to.'}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['rows', 'totalCount', 'returned', 'success'], 'properties': {'rows': {'type': 'array', 'items': {'type': 'object', 'propertyNames': {'type': 'string'}, 'additionalProperties': {}}, 'description': 'Query results'}, 'error': {'type': 'string'}, 'columns': {'type': 'array', 'items': {'type': 'string'}, '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."}, 'success': {'type': 'boolean'}, 'returned': {'type': 'number', 'description': 'Number of rows returned'}, 'columnMeta': {'type': 'object', 'description': '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.', 'propertyNames': {'type': 'string'}, 'additionalProperties': {'type': 'object', 'properties': {'context': {'type': 'string'}, 'enrichment': {'type': 'string'}}, 'additionalProperties': False}}, 'nextCursor': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': 'Cursor for the next page. null means last page.'}, 'totalCount': {'type': 'number', 'description': 'Total matching records'}, 'records_url': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "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': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_remove_contact_channel

Remove contact channel

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.

Destructive

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['parent', 'parent_id', 'channel', 'channel_id'], 'properties': {'parent': {'enum': ['company', 'person'], 'type': 'string', 'description': 'Parent record type: company or person'}, 'channel': {'enum': ['email', 'phone', 'web_link', 'location'], 'type': 'string', 'description': 'Channel to remove: email | phone | web_link | location'}, 'parent_id': {'type': 'string', '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)$', 'description': 'UUID of the parent company or person'}, 'channel_id': {'type': 'string', '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)$', 'description': 'UUID of the specific channel row to remove'}, 'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.'}, 'conversation_id': {'type': 'string', '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.'}, 'idempotency_key': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'error': {'type': 'string'}, 'parent': {'type': 'string'}, 'channel': {'type': 'string'}, 'success': {'type': 'boolean'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_render_burn

Render a caller-computed burn

Put a burn figure YOU computed onto the burn card. **This tool measures nothing.** It takes the figure and its method as input and returns them for rendering. Call it only after you have computed the burn yourself and can state every field below from your own work — never to "get" a burn. The server derives no burn of its own. The figure on the card is the one you state here, which is why every field below is required: the policy behind a number is the only thing that makes it checkable. **Under the number the card draws nothing.** It carries the figure, the window it averages and the trend chip; everything else you state below is REQUIRED and reaches no pixel. All of it comes back to you in this tool's text result, which is what you write the prose from. The card is the measure; the explanation is yours. REQUIRED, because a figure whose method is not stated cannot be checked: - `amount` — the outflow per month, as a POSITIVE magnitude in `currency` - `window` — the months the average divides by, not the months that carried spend - `convention` — "signed", and the counts you elected it from - `months_in_window` and `months_with_data` — a window with dark months reports LOWER than its typical month. When the two differ you MUST say so in prose: how many months recorded an outflow, and that the average still divides by the whole window - `excluded` — what fell out, in named groups. `internal_transfers` is the sum's `excluded_multi_leg`; send `null` when the sum could not count it - `transaction_count` and `unplaceable_count` — how much of the window could be placed inside or outside the transfer rule at all. `unplaceable_count` is the sum's `excluded_no_owned_leg`. Send `null` when the sum could not count it. Never send 0 for that, because zero says every row was placed REFUSED rather than rendered: - a negative `amount` — a burn is a magnitude; a negative one means a signed subtotal was used without taking its magnitude - `convention: "magnitude"` — that feed keeps direction in a field no grouping here reaches, so no outflow was measured - `months_with_data` above `months_in_window`, or a measured `unplaceable_count` above `transaction_count` - one of `unplaceable_count` and `excluded.internal_transfers` `null` without the other: one cancelled count nulls both - a `months_in_window` that disagrees with the months `window` spans — the two state one fact, and a reader cannot tell which is the lie - `signed` elected from ZERO negative rows: whatever the convention was called, that window measured no outflow - `convention_counts` summing past `transaction_count`, or `months_with_data` disagreeing with the months `per_month` shows carrying an outflow — your own prose states both, so a contradiction between them is a sentence that refutes itself - a `window` whose bounds are not each the first of a month, or that fits inside one month: a month average divides by whole months - a `per_month` series that is not the window's own months, in order, averaging to `amount` — a dark month belongs in it as a zero, and a series that disagrees with the figure is not the working behind it - a `currency` outside ISO-4217 — the code is checked against the catalog, not its shape OPTIONAL, and only as a pair: - `baseline` and `change` — the earlier window you compared against, its own average, and the signed percentage between them. Send both or neither: a percentage whose baseline the reader cannot name is exactly the unchecked number this tool refuses everywhere else. The card draws the CHIP alone and never the baseline, so sending the pair obliges you to NAME that comparison in prose: the baseline window and its own average. Compute the baseline the same way you computed the figure, over a window of the same length; the two may overlap, and when they do say so too. `change` is checked against `amount` and `baseline.value` and refused when it does not follow from them, so send the percentage you actually divided. Do not send a direction: down is GOOD for a burn, and the card's green is decided server-side from `change` rather than read off its sign. When the token authorizes one workspace, call this directly — no other tool call is needed first. When it authorizes several, this read will not guess which one you mean: pass `workspace_id` on the call.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['amount', 'currency', 'window', 'months_in_window', 'months_with_data', 'convention', 'convention_counts', 'transaction_count', 'unplaceable_count', 'excluded'], 'properties': {'amount': {'type': 'number', 'minimum': 0, 'description': 'Average monthly outflow as a POSITIVE magnitude. A negative value is refused.'}, 'change': {'type': 'number', 'description': "Signed percentage against `baseline.value`, drawn as the card's trend chip. Send it only alongside `baseline`, whose window and average your prose must name, and never derive the card's up/down sense from its sign — for a burn, down is good."}, 'window': {'type': 'object', 'required': ['from', 'to'], 'properties': {'to': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$'}, 'from': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$'}}, 'description': 'Inclusive start and EXCLUSIVE end of the averaged window, YYYY-MM-DD.'}, 'baseline': {'type': 'object', 'required': ['value', 'period'], 'properties': {'value': {'type': 'number', 'description': "The baseline window's own average, as a POSITIVE magnitude. Zero is refused: a percentage against nothing is a division nobody can perform.", 'exclusiveMinimum': 0}, 'period': {'type': 'object', 'required': ['from', 'to'], 'properties': {'to': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$'}, 'from': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$'}}}}, 'description': 'The earlier window this figure is compared against, and its own average. Required for `change` to render, and never rendered itself: name it in prose, because a percentage whose baseline the reader cannot find anywhere is a number they cannot check.'}, 'currency': {'enum': ['USD', 'EUR', 'GBP', 'JPY', 'CHF', 'CAD', 'AUD', 'NZD', 'SEK', 'NOK', 'DKK', 'PLN', 'CZK', 'HUF', 'RON', 'BGN', 'HRK', 'ISK', 'ALL', 'BAM', 'BYN', 'MDL', 'MKD', 'RSD', 'FOK', 'GGP', 'GIP', 'IMP', 'JEP', 'CNY', 'CNH', 'KRW', 'SGD', 'HKD', 'TWD', 'THB', 'MYR', 'IDR', 'PHP', 'VND', 'INR', 'PKR', 'LKR', 'BDT', 'BND', 'BTN', 'KHR', 'LAK', 'MMK', 'MNT', 'MOP', 'MVR', 'NPR', 'KID', 'AED', 'SAR', 'QAR', 'KWD', 'BHD', 'OMR', 'JOD', 'ILS', 'EGP', 'ZAR', 'NGN', 'KES', 'GHS', 'MAD', 'TND', 'DZD', 'CVE', 'GMD', 'GNF', 'LRD', 'MGA', 'MRU', 'SHP', 'SLE', 'SLL', 'SSP', 'STN', 'YER', 'MXN', 'BRL', 'ARS', 'CLP', 'COP', 'PEN', 'UYU', 'VES', 'GTQ', 'HNL', 'NIO', 'CRC', 'PAB', 'DOP', 'JMD', 'TTD', 'BBD', 'XCD', 'ANG', 'AWG', 'BMD', 'BOB', 'BSD', 'BZD', 'CUP', 'GYD', 'HTG', 'KYD', 'PYG', 'SRD', 'XCG', 'FKP', 'FJD', 'PGK', 'SBD', 'TOP', 'TVD', 'VUV', 'WST', 'RUB', 'TRY', 'UAH', 'KZT', 'UZS', 'AZN', 'GEL', 'AMD', 'KGS', 'TJS', 'TMT', 'AFN', 'IRR', 'IQD', 'SYP', 'LBP', 'LYD', 'SDG', 'ETB', 'UGX', 'TZS', 'MWK', 'ZMW', 'BWP', 'SZL', 'LSL', 'NAD', 'MUR', 'SCR', 'KMF', 'DJF', 'ERN', 'SOS', 'AOA', 'MZN', 'ZWL', 'ZWG', 'BIF', 'RWF', 'CDF', 'XAF', 'XOF', 'XPF'], 'type': 'string', 'description': 'ISO-4217 code the amount is denominated in. Checked against the catalog, not its shape.'}, 'excluded': {'type': 'object', 'required': ['internal_transfers', 'exempt_categories', 'unreadable_rows'], 'properties': {'unreadable_rows': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'exempt_categories': {'type': 'array', 'items': {'type': 'string'}, 'maxItems': 100}, 'internal_transfers': {'anyOf': [{'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, {'type': 'null'}], 'description': "The sum's `excluded_multi_leg`. `null` when the sum could not count it, never 0."}}, 'description': 'The three exclusion groups kept apart: structural, reader-chosen, and defective.'}, 'per_month': {'type': 'array', 'items': {'type': 'object', 'required': ['month', 'amount'], 'properties': {'month': {'type': 'string'}, 'amount': {'type': 'number'}}}, 'description': 'The series behind the average. A month with no outflow belongs in it as a zero.'}, 'convention': {'enum': ['signed', 'magnitude'], 'type': 'string', 'description': 'Which sign the feed uses for an outflow. "magnitude" is refused: it measures no outflow.'}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which."}, 'conversation_id': {'type': 'string', '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.'}, 'months_in_window': {'type': 'integer', 'maximum': 9007199254740991, 'description': 'The divisor — every month in the window.', 'exclusiveMinimum': 0}, 'months_with_data': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0, 'description': 'How many of those months carried any outflow.'}, 'convention_counts': {'type': 'object', 'required': ['negative', 'positive'], 'properties': {'negative': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'positive': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}}, 'description': 'The row counts the convention was elected from, so a reader can check the election.'}, 'transaction_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0, 'description': 'Rows in the window.'}, 'unplaceable_count': {'anyOf': [{'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, {'type': 'null'}], 'description': "Rows with no leg on an owned account, neither inside nor outside the transfer rule: the sum's `excluded_no_owned_leg`. `null` when the sum could not count them, never 0."}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['amount', 'currency', 'window', 'months_in_window', 'months_with_data', 'convention', 'convention_counts', 'transaction_count', 'unplaceable_count', 'excluded', 'computed_by', 'success'], 'properties': {'trend': {'enum': ['up', 'down', 'neutral'], 'type': 'string'}, 'amount': {'type': 'number'}, 'change': {'type': 'number'}, 'window': {'type': 'object', 'required': ['from', 'to'], 'properties': {'to': {'type': 'string'}, 'from': {'type': 'string'}}, 'additionalProperties': False}, 'success': {'type': 'boolean'}, 'baseline': {'type': 'object', 'required': ['value', 'period'], 'properties': {'value': {'type': 'number'}, 'period': {'type': 'object', 'required': ['from', 'to'], 'properties': {'to': {'type': 'string'}, 'from': {'type': 'string'}}, 'additionalProperties': False}}, 'additionalProperties': False}, 'currency': {'type': 'string'}, 'excluded': {'type': 'object', 'required': ['internal_transfers', 'exempt_categories', 'unreadable_rows'], 'properties': {'unreadable_rows': {'type': 'number'}, 'exempt_categories': {'type': 'array', 'items': {'type': 'string'}}, 'internal_transfers': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}}, 'additionalProperties': False}, 'per_month': {'type': 'array', 'items': {'type': 'object', 'required': ['month', 'amount'], 'properties': {'month': {'type': 'string'}, 'amount': {'type': 'number'}}, 'additionalProperties': False}}, 'convention': {'type': 'string'}, 'computed_by': {'type': 'string', 'const': 'caller'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'months_in_window': {'type': 'number'}, 'months_with_data': {'type': 'number'}, 'convention_counts': {'type': 'object', 'required': ['negative', 'positive'], 'properties': {'negative': {'type': 'number'}, 'positive': {'type': 'number'}}, 'additionalProperties': False}, 'transaction_count': {'type': 'number'}, 'unplaceable_count': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_render_cash_flow_bridge

Render a caller-computed cash-flow bridge

Put a cash-flow bridge YOU computed onto the cash-flow waterfall card. **This tool measures nothing.** It takes the four terms of a bridge and the gap between them as input, draws the waterfall, and returns them. Call it only after you have read the opening and closing positions and summed the window's flows yourself — never to "get" a bridge. A bridge rests on one law: the opening, plus the inflows, minus the outflows, lands on the closing. The closing is measured on its own rather than summed from the flows, so the law is a check rather than a given. State the gap as `unexplained` and the tool verifies the five figures add up; state figures that do not and it refuses. REQUIRED: - `currency` — every figure below is in it, each converted before you stated it - `period_start`, `period_end` — the inclusive calendar days the flows cover - `opening` — `amount` (SIGNED, a workspace can be overdrawn), `as_of` (the day before `period_start`), and `derived` (true only when you solved it from the law because the reading could not be taken) - `inflows`, `outflows` — gross magnitudes, both positive; the direction lives in which bar they are - `unexplained` — the SIGNED gap `closing - (opening + inflows - outflows)`, computed from the figures as you rounded them; zero when they meet - `closing` — `amount` (SIGNED) and `as_of`, the moment the reading was taken - `reconciles` — true when the gap is inside the tolerance below, false when it is past it - `partial` — true when any term is incomplete: an anchor some accounts had no reading for, flows with rows no owned account could be placed against, rows that could not be read, or a currency with no rate. A cut-short read returns no rows and stops the run before this call The tolerance is the product's own: 1% of the closing position's size, never less than 1 in the base currency. A bridge that does not reconcile draws an Unexplained bar between the outflows and the closing; one that does draws none. REFUSED rather than rendered, each because your own figures disagree: - five figures that do not add up to within a cent - `reconciles: true` with a gap past the tolerance, or `false` with one inside it - a negative `inflows` or `outflows`; each is a magnitude, so a negative one was re-signed - an opening not dated the day before `period_start` - a window ending more than a day from the day the closing was read - a window that starts after it ends, or a date that names no real day - a derived opening with any gap, on a partial read, or over a window with no flows - a closing `as_of` in the future When the token authorizes one workspace, call this directly — no other tool call is needed first. When it authorizes several, this read will not guess which one you mean: pass `workspace_id` on the call.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['currency', 'period_start', 'period_end', 'opening', 'inflows', 'outflows', 'unexplained', 'closing', 'reconciles', 'partial'], 'properties': {'closing': {'type': 'object', 'required': ['amount', 'as_of'], 'properties': {'as_of': {'type': 'string', 'format': 'date-time', 'pattern': '^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$'}, 'amount': {'type': 'number'}}, 'additionalProperties': False}, 'inflows': {'type': 'number'}, 'opening': {'type': 'object', 'required': ['amount', 'as_of', 'derived'], 'properties': {'as_of': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$'}, 'amount': {'type': 'number'}, 'derived': {'type': 'boolean'}}, 'additionalProperties': False}, 'partial': {'type': 'boolean'}, 'currency': {'enum': ['USD', 'EUR', 'GBP', 'JPY', 'CHF', 'CAD', 'AUD', 'NZD', 'SEK', 'NOK', 'DKK', 'PLN', 'CZK', 'HUF', 'RON', 'BGN', 'HRK', 'ISK', 'ALL', 'BAM', 'BYN', 'MDL', 'MKD', 'RSD', 'FOK', 'GGP', 'GIP', 'IMP', 'JEP', 'CNY', 'CNH', 'KRW', 'SGD', 'HKD', 'TWD', 'THB', 'MYR', 'IDR', 'PHP', 'VND', 'INR', 'PKR', 'LKR', 'BDT', 'BND', 'BTN', 'KHR', 'LAK', 'MMK', 'MNT', 'MOP', 'MVR', 'NPR', 'KID', 'AED', 'SAR', 'QAR', 'KWD', 'BHD', 'OMR', 'JOD', 'ILS', 'EGP', 'ZAR', 'NGN', 'KES', 'GHS', 'MAD', 'TND', 'DZD', 'CVE', 'GMD', 'GNF', 'LRD', 'MGA', 'MRU', 'SHP', 'SLE', 'SLL', 'SSP', 'STN', 'YER', 'MXN', 'BRL', 'ARS', 'CLP', 'COP', 'PEN', 'UYU', 'VES', 'GTQ', 'HNL', 'NIO', 'CRC', 'PAB', 'DOP', 'JMD', 'TTD', 'BBD', 'XCD', 'ANG', 'AWG', 'BMD', 'BOB', 'BSD', 'BZD', 'CUP', 'GYD', 'HTG', 'KYD', 'PYG', 'SRD', 'XCG', 'FKP', 'FJD', 'PGK', 'SBD', 'TOP', 'TVD', 'VUV', 'WST', 'RUB', 'TRY', 'UAH', 'KZT', 'UZS', 'AZN', 'GEL', 'AMD', 'KGS', 'TJS', 'TMT', 'AFN', 'IRR', 'IQD', 'SYP', 'LBP', 'LYD', 'SDG', 'ETB', 'UGX', 'TZS', 'MWK', 'ZMW', 'BWP', 'SZL', 'LSL', 'NAD', 'MUR', 'SCR', 'KMF', 'DJF', 'ERN', 'SOS', 'AOA', 'MZN', 'ZWL', 'ZWG', 'BIF', 'RWF', 'CDF', 'XAF', 'XOF', 'XPF'], 'type': 'string'}, 'outflows': {'type': 'number'}, 'period_end': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$'}, 'reconciles': {'type': 'boolean'}, 'unexplained': {'type': 'number'}, 'period_start': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$'}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which."}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['currency', 'period_start', 'period_end', 'opening', 'inflows', 'outflows', 'unexplained', 'closing', 'reconciles', 'partial', 'steps', 'computed_by', 'success'], 'properties': {'steps': {'type': 'array', 'items': {'type': 'object', 'required': ['label', 'value', 'kind'], 'properties': {'kind': {'enum': ['start', 'increase', 'decrease', 'total', 'unexplained'], 'type': 'string'}, 'label': {'type': 'string'}, 'value': {'type': 'number'}}, 'additionalProperties': False}}, 'closing': {'type': 'object', 'required': ['amount', 'as_of'], 'properties': {'as_of': {'type': 'string'}, 'amount': {'type': 'number'}}, 'additionalProperties': False}, 'inflows': {'type': 'number'}, 'opening': {'type': 'object', 'required': ['amount', 'as_of', 'derived'], 'properties': {'as_of': {'type': 'string'}, 'amount': {'type': 'number'}, 'derived': {'type': 'boolean'}}, 'additionalProperties': False}, 'partial': {'type': 'boolean'}, 'success': {'type': 'boolean'}, 'currency': {'type': 'string'}, 'outflows': {'type': 'number'}, 'period_end': {'type': 'string'}, 'reconciles': {'type': 'boolean'}, 'computed_by': {'type': 'string', 'const': 'caller'}, 'unexplained': {'type': 'number'}, 'period_start': {'type': 'string'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_render_cash_forecast

Render a caller-computed cash forecast

Put a cash forecast YOU computed onto the forecast card. **This tool measures nothing.** It takes the settled month-end series, the anchor, the burn and the projection you computed, and returns them for rendering. Call it only after you have computed both halves yourself: the month-end totals under your cash scope, and the burn under your stated policy. Never call it to "get" a forecast. The projection is WORST CASE: no revenue arrives, and cash declines by the burn each month until it reaches zero, where it stops. Take the anchor and the burn each to the cent, then each point is `max(0, anchor − k × burn)` for the k-th month after the anchor. The tool re-derives every point from the anchor and burn you state here, in cents. **The card draws the series, the anchor clause and the worst-case caveat.** The cash scope, the burn policy and `partial` are REQUIRED and reach no pixel. All of it comes back in this tool's text result, which is what you write the prose from. REQUIRED: - `currency`, and `as_of`: the full ISO time of the balances read the series came from - `actuals`: one `{ month, amount }` per month, oldest first, ending on the last month that has ended at `as_of` (UTC). A month no account covered is `null`, never 0, and it stays in the list. - `anchor`: `{ month, amount, basis }`. `closed_month_end` is the latest settled month-end in `actuals`. `current_position` is today's cash when no month has a settled total. It sits on the grid at the last actual month. - `burn`: the POSITIVE monthly magnitude, its currency, `trailing_months`, and the `window` it averaged (`from` inclusive and `to` exclusive, each `YYYY-MM-01`). The window ends with the last actual month. - `months_forward` (at most 12), and `projection`: one `{ month, amount }` per projected month. When the anchor sits before the last actual month, the months between are projected too, so `months_forward` must reach past them. - `cash_scope`: the counted account types, whether unknown ownership was counted, `anchor_missing_accounts` (counted accounts with no reading at a closed-month anchor; 0 under `current_position`), and the four exclusion groups - `burn_policy`: the elected convention and its counts, the exclusions (`internal_transfers` is the sum's `excluded_multi_leg`, `unreadable_rows` its malformed rows), and `unplaceable_count` (the sum's `excluded_no_owned_leg`) - `partial`: the forecast's own floor, which is WIDER than a cash total's `is_floor`. It is checked against `cash_scope` and must be `true` exactly when an account was left out with no readable balance, no rate, OR no reading at the anchor month — that last one is the forecast's alone, and a caller that forwards its cash total's `is_floor` unchanged is refused on it. It never means a cut-short read: a cut-short balances read or sum stops the run before this call. REFUSED rather than rendered, each because your own figures disagree: - a projection point that is not `max(0, anchor − k × burn)` within a cent - a projection that does not start the month after the anchor, skips a month, continues after a zero, or has the wrong length - a projection ending on a month that has already ended. The refusal names which of the three causes fired: the cash ran out (report that), the horizon was too narrow for the gap (widen it), or the gap exceeds every legal horizon (the feed is too far behind to project across) - a cash currency that differs from the burn's - a negative burn, a burn elected "magnitude", `signed` elected from no negative rows, or one of `unplaceable_count` and `internal_transfers` null without the other - a `closed_month_end` anchor that is not the latest settled actual, or whose amount differs from it - a `current_position` anchor beside a settled actual, off the last actual month, or with an account missing at it - actual months out of order, repeated, skipped, or ending on any month but the last one that has ended at `as_of` - a burn window that disagrees with `trailing_months`, or ends on a different month than the actuals - a `partial` that disagrees with the floor your own `cash_scope` implies - an `as_of` in the future This tool renders its own chart card. Do not re-plot the series with a charting tool. When the token authorizes one workspace, call this directly — no other tool call is needed first. When it authorizes several, this read will not guess which one you mean: pass `workspace_id` on the call.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['currency', 'as_of', 'actuals', 'anchor', 'burn', 'months_forward', 'projection', 'cash_scope', 'burn_policy', 'partial'], 'properties': {'burn': {'type': 'object', 'required': ['amount', 'currency', 'trailing_months', 'window'], 'properties': {'amount': {'type': 'number'}, 'window': {'type': 'object', 'required': ['from', 'to'], 'properties': {'to': {'type': 'string', 'pattern': '^\\d{4}-(0[1-9]|1[0-2])-\\d{2}$'}, 'from': {'type': 'string', 'pattern': '^\\d{4}-(0[1-9]|1[0-2])-\\d{2}$'}}}, 'currency': {'enum': ['USD', 'EUR', 'GBP', 'JPY', 'CHF', 'CAD', 'AUD', 'NZD', 'SEK', 'NOK', 'DKK', 'PLN', 'CZK', 'HUF', 'RON', 'BGN', 'HRK', 'ISK', 'ALL', 'BAM', 'BYN', 'MDL', 'MKD', 'RSD', 'FOK', 'GGP', 'GIP', 'IMP', 'JEP', 'CNY', 'CNH', 'KRW', 'SGD', 'HKD', 'TWD', 'THB', 'MYR', 'IDR', 'PHP', 'VND', 'INR', 'PKR', 'LKR', 'BDT', 'BND', 'BTN', 'KHR', 'LAK', 'MMK', 'MNT', 'MOP', 'MVR', 'NPR', 'KID', 'AED', 'SAR', 'QAR', 'KWD', 'BHD', 'OMR', 'JOD', 'ILS', 'EGP', 'ZAR', 'NGN', 'KES', 'GHS', 'MAD', 'TND', 'DZD', 'CVE', 'GMD', 'GNF', 'LRD', 'MGA', 'MRU', 'SHP', 'SLE', 'SLL', 'SSP', 'STN', 'YER', 'MXN', 'BRL', 'ARS', 'CLP', 'COP', 'PEN', 'UYU', 'VES', 'GTQ', 'HNL', 'NIO', 'CRC', 'PAB', 'DOP', 'JMD', 'TTD', 'BBD', 'XCD', 'ANG', 'AWG', 'BMD', 'BOB', 'BSD', 'BZD', 'CUP', 'GYD', 'HTG', 'KYD', 'PYG', 'SRD', 'XCG', 'FKP', 'FJD', 'PGK', 'SBD', 'TOP', 'TVD', 'VUV', 'WST', 'RUB', 'TRY', 'UAH', 'KZT', 'UZS', 'AZN', 'GEL', 'AMD', 'KGS', 'TJS', 'TMT', 'AFN', 'IRR', 'IQD', 'SYP', 'LBP', 'LYD', 'SDG', 'ETB', 'UGX', 'TZS', 'MWK', 'ZMW', 'BWP', 'SZL', 'LSL', 'NAD', 'MUR', 'SCR', 'KMF', 'DJF', 'ERN', 'SOS', 'AOA', 'MZN', 'ZWL', 'ZWG', 'BIF', 'RWF', 'CDF', 'XAF', 'XOF', 'XPF'], 'type': 'string'}, 'trailing_months': {'type': 'integer', 'maximum': 9007199254740991, 'exclusiveMinimum': 0}}}, 'as_of': {'type': 'string', 'format': 'date-time', 'pattern': '^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$'}, 'anchor': {'type': 'object', 'required': ['month', 'amount', 'basis'], 'properties': {'basis': {'enum': ['closed_month_end', 'current_position'], 'type': 'string'}, 'month': {'type': 'string', 'pattern': '^\\d{4}-(0[1-9]|1[0-2])$'}, 'amount': {'type': 'number'}}}, 'actuals': {'type': 'array', 'items': {'type': 'object', 'required': ['month', 'amount'], 'properties': {'month': {'type': 'string', 'pattern': '^\\d{4}-(0[1-9]|1[0-2])$'}, 'amount': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}}}, 'maxItems': 24, 'minItems': 1}, 'partial': {'type': 'boolean'}, 'currency': {'enum': ['USD', 'EUR', 'GBP', 'JPY', 'CHF', 'CAD', 'AUD', 'NZD', 'SEK', 'NOK', 'DKK', 'PLN', 'CZK', 'HUF', 'RON', 'BGN', 'HRK', 'ISK', 'ALL', 'BAM', 'BYN', 'MDL', 'MKD', 'RSD', 'FOK', 'GGP', 'GIP', 'IMP', 'JEP', 'CNY', 'CNH', 'KRW', 'SGD', 'HKD', 'TWD', 'THB', 'MYR', 'IDR', 'PHP', 'VND', 'INR', 'PKR', 'LKR', 'BDT', 'BND', 'BTN', 'KHR', 'LAK', 'MMK', 'MNT', 'MOP', 'MVR', 'NPR', 'KID', 'AED', 'SAR', 'QAR', 'KWD', 'BHD', 'OMR', 'JOD', 'ILS', 'EGP', 'ZAR', 'NGN', 'KES', 'GHS', 'MAD', 'TND', 'DZD', 'CVE', 'GMD', 'GNF', 'LRD', 'MGA', 'MRU', 'SHP', 'SLE', 'SLL', 'SSP', 'STN', 'YER', 'MXN', 'BRL', 'ARS', 'CLP', 'COP', 'PEN', 'UYU', 'VES', 'GTQ', 'HNL', 'NIO', 'CRC', 'PAB', 'DOP', 'JMD', 'TTD', 'BBD', 'XCD', 'ANG', 'AWG', 'BMD', 'BOB', 'BSD', 'BZD', 'CUP', 'GYD', 'HTG', 'KYD', 'PYG', 'SRD', 'XCG', 'FKP', 'FJD', 'PGK', 'SBD', 'TOP', 'TVD', 'VUV', 'WST', 'RUB', 'TRY', 'UAH', 'KZT', 'UZS', 'AZN', 'GEL', 'AMD', 'KGS', 'TJS', 'TMT', 'AFN', 'IRR', 'IQD', 'SYP', 'LBP', 'LYD', 'SDG', 'ETB', 'UGX', 'TZS', 'MWK', 'ZMW', 'BWP', 'SZL', 'LSL', 'NAD', 'MUR', 'SCR', 'KMF', 'DJF', 'ERN', 'SOS', 'AOA', 'MZN', 'ZWL', 'ZWG', 'BIF', 'RWF', 'CDF', 'XAF', 'XOF', 'XPF'], 'type': 'string'}, 'cash_scope': {'type': 'object', 'required': ['account_types', 'counted_unknown_ownership', 'anchor_missing_accounts', 'excluded'], 'properties': {'excluded': {'type': 'object', 'required': ['not_owned', 'out_of_scope_type', 'no_readable_balance', 'no_fx_rate'], 'properties': {'not_owned': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'no_fx_rate': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'out_of_scope_type': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'no_readable_balance': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}}}, 'account_types': {'type': 'array', 'items': {'enum': ['deposit', 'credit', 'loan', 'investment', 'payroll', 'other'], 'type': 'string'}, 'minItems': 1}, 'anchor_missing_accounts': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'counted_unknown_ownership': {'type': 'boolean'}}}, 'projection': {'type': 'array', 'items': {'type': 'object', 'required': ['month', 'amount'], 'properties': {'month': {'type': 'string', 'pattern': '^\\d{4}-(0[1-9]|1[0-2])$'}, 'amount': {'type': 'number'}}}, 'maxItems': 12, 'minItems': 1}, 'burn_policy': {'type': 'object', 'required': ['convention', 'convention_counts', 'excluded', 'unplaceable_count'], 'properties': {'excluded': {'type': 'object', 'required': ['internal_transfers', 'exempt_categories', 'unreadable_rows'], 'properties': {'unreadable_rows': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'exempt_categories': {'type': 'array', 'items': {'type': 'string', 'maxLength': 200}, 'maxItems': 100}, 'internal_transfers': {'anyOf': [{'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, {'type': 'null'}]}}}, 'convention': {'enum': ['signed', 'magnitude'], 'type': 'string'}, 'convention_counts': {'type': 'object', 'required': ['negative', 'positive'], 'properties': {'negative': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'positive': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}}}, 'unplaceable_count': {'anyOf': [{'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, {'type': 'null'}]}}}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which."}, 'months_forward': {'type': 'integer', 'maximum': 12, 'exclusiveMinimum': 0}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['entries', 'currency', 'as_of', 'anchor', 'burn', 'months_forward', 'cash_scope', 'burn_policy', 'partial', 'computed_by', 'success'], 'properties': {'burn': {'type': 'object', 'required': ['amount', 'currency', 'trailing_months', 'window'], 'properties': {'amount': {'type': 'number'}, 'window': {'type': 'object', 'required': ['from', 'to'], 'properties': {'to': {'type': 'string'}, 'from': {'type': 'string'}}, 'additionalProperties': False}, 'currency': {'type': 'string'}, 'trailing_months': {'type': 'number'}}, 'additionalProperties': False}, 'as_of': {'type': 'string'}, 'anchor': {'type': 'object', 'required': ['month', 'amount', 'basis'], 'properties': {'basis': {'enum': ['closed_month_end', 'current_position'], 'type': 'string'}, 'month': {'type': 'string'}, 'amount': {'type': 'number'}}, 'additionalProperties': False}, 'entries': {'type': 'array', 'items': {'type': 'object', 'required': ['month', 'actuals', 'projection'], 'properties': {'month': {'type': 'string'}, 'actuals': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'projection': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}}, 'additionalProperties': False}}, 'partial': {'type': 'boolean'}, 'success': {'type': 'boolean'}, 'currency': {'type': 'string'}, 'cash_scope': {'type': 'object', 'required': ['account_types', 'counted_unknown_ownership', 'anchor_missing_accounts', 'excluded'], 'properties': {'excluded': {'type': 'object', 'required': ['not_owned', 'out_of_scope_type', 'no_readable_balance', 'no_fx_rate'], 'properties': {'not_owned': {'type': 'number'}, 'no_fx_rate': {'type': 'number'}, 'out_of_scope_type': {'type': 'number'}, 'no_readable_balance': {'type': 'number'}}, 'additionalProperties': False}, 'account_types': {'type': 'array', 'items': {'type': 'string'}}, 'anchor_missing_accounts': {'type': 'number'}, 'counted_unknown_ownership': {'type': 'boolean'}}, 'additionalProperties': False}, 'burn_policy': {'type': 'object', 'required': ['convention', 'convention_counts', 'excluded', 'unplaceable_count'], 'properties': {'excluded': {'type': 'object', 'required': ['internal_transfers', 'exempt_categories', 'unreadable_rows'], 'properties': {'unreadable_rows': {'type': 'number'}, 'exempt_categories': {'type': 'array', 'items': {'type': 'string'}}, 'internal_transfers': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}}, 'additionalProperties': False}, 'convention': {'type': 'string'}, 'convention_counts': {'type': 'object', 'required': ['negative', 'positive'], 'properties': {'negative': {'type': 'number'}, 'positive': {'type': 'number'}}, 'additionalProperties': False}, 'unplaceable_count': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}}, 'additionalProperties': False}, 'computed_by': {'type': 'string', 'const': 'caller'}, 'months_forward': {'type': 'number'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_render_cash_position

Render a caller-computed cash position

Put a cash position YOU computed onto the cash card. **This tool measures nothing.** It takes the figure and its method as input and returns them for rendering. Call it only after you have totalled the balances yourself and can state every field below from your own work — never to "get" a cash position. The server derives no cash figure of its own here, which is why every field below is required: the policy behind a number is the only thing that makes it checkable. **Under the number the card draws nothing.** It carries the total and the moment it was read. Every other field below, required or optional, reaches no pixel. All of it comes back in this tool's text result, which is what you write the prose from. The card is the measure; the explanation is yours. REQUIRED, because a figure whose method is not stated cannot be checked: - `amount` and `currency` — the consolidated total. NEGATIVE is legal: an overdrawn workspace has negative cash, and this tool renders it rather than refusing it. - `as_of` — the moment the reading is valid for - `accounts` — every account that CONTRIBUTED, each with its native amount and currency, the converted amount, and the rate applied (`null` when it was already in `currency`). Carry `institution_name` and `masked_account_number` through from the balances read as well: your breakdown names each account by its bank, its name and its masked suffix, or by its currency when the bank and the name are both `null`, and never by its id. - `scope` — the account types you counted as cash, and whether you counted an account whose ownership is unsettled - `excluded` — what fell out, in four named groups: not owned, out-of-scope type, no readable balance, no FX rate. One merged count hides the difference between a rule the reader chose and a defect in the data. - `partial` — whether the total may be a floor (the skills' `is_floor`), because an account with no readable balance or no rate was left out of it. The result carries the value derived from `excluded`, whatever you state. It never means a cut-short read: that stops before this call. REFUSED rather than rendered, each because the caller's own figures disagree with each other: - a total that is not the sum of the contributions listed — totalling a different set than you disclose publishes a figure nobody can audit - a converted amount that does not follow from its native amount and stated rate - an account already in `currency` that carries a rate other than one, or whose converted amount differs from its native one - an account in another currency that states no rate - the same account contributing twice - a non-zero total with no contributing accounts - an `as_of` in the future - a `scope.account_types` naming nothing - a `balance_history` that repeats a month or runs out of order - a currency outside ISO-4217 — checked against the catalog, not its shape OPTIONAL: - `balance_history` — trailing complete month ends, oldest first. A `null` amount is a month no stored row covered; send it as a gap rather than dropping it or sending a zero, and never interpolate between two real points. When the token authorizes one workspace, call this directly — no other tool call is needed first. When it authorizes several, this read will not guess which one you mean: pass `workspace_id` on the call.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['amount', 'currency', 'as_of', 'accounts', 'scope', 'excluded', 'partial'], 'properties': {'as_of': {'type': 'string', 'format': 'date-time', 'pattern': '^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$'}, 'scope': {'type': 'object', 'required': ['account_types', 'counted_unknown_ownership'], 'properties': {'account_types': {'type': 'array', 'items': {'enum': ['deposit', 'credit', 'loan', 'investment', 'payroll', 'other'], 'type': 'string'}, 'minItems': 1}, 'counted_unknown_ownership': {'type': 'boolean'}}}, 'amount': {'type': 'number'}, 'partial': {'type': 'boolean'}, 'accounts': {'type': 'array', 'items': {'type': 'object', 'required': ['account_id', 'account_name', 'institution_name', 'masked_account_number', 'native_amount', 'native_currency', 'converted_amount', 'fx_rate'], 'properties': {'fx_rate': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'account_id': {'type': 'string', 'minLength': 1}, 'account_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'native_amount': {'type': 'number'}, 'native_currency': {'enum': ['USD', 'EUR', 'GBP', 'JPY', 'CHF', 'CAD', 'AUD', 'NZD', 'SEK', 'NOK', 'DKK', 'PLN', 'CZK', 'HUF', 'RON', 'BGN', 'HRK', 'ISK', 'ALL', 'BAM', 'BYN', 'MDL', 'MKD', 'RSD', 'FOK', 'GGP', 'GIP', 'IMP', 'JEP', 'CNY', 'CNH', 'KRW', 'SGD', 'HKD', 'TWD', 'THB', 'MYR', 'IDR', 'PHP', 'VND', 'INR', 'PKR', 'LKR', 'BDT', 'BND', 'BTN', 'KHR', 'LAK', 'MMK', 'MNT', 'MOP', 'MVR', 'NPR', 'KID', 'AED', 'SAR', 'QAR', 'KWD', 'BHD', 'OMR', 'JOD', 'ILS', 'EGP', 'ZAR', 'NGN', 'KES', 'GHS', 'MAD', 'TND', 'DZD', 'CVE', 'GMD', 'GNF', 'LRD', 'MGA', 'MRU', 'SHP', 'SLE', 'SLL', 'SSP', 'STN', 'YER', 'MXN', 'BRL', 'ARS', 'CLP', 'COP', 'PEN', 'UYU', 'VES', 'GTQ', 'HNL', 'NIO', 'CRC', 'PAB', 'DOP', 'JMD', 'TTD', 'BBD', 'XCD', 'ANG', 'AWG', 'BMD', 'BOB', 'BSD', 'BZD', 'CUP', 'GYD', 'HTG', 'KYD', 'PYG', 'SRD', 'XCG', 'FKP', 'FJD', 'PGK', 'SBD', 'TOP', 'TVD', 'VUV', 'WST', 'RUB', 'TRY', 'UAH', 'KZT', 'UZS', 'AZN', 'GEL', 'AMD', 'KGS', 'TJS', 'TMT', 'AFN', 'IRR', 'IQD', 'SYP', 'LBP', 'LYD', 'SDG', 'ETB', 'UGX', 'TZS', 'MWK', 'ZMW', 'BWP', 'SZL', 'LSL', 'NAD', 'MUR', 'SCR', 'KMF', 'DJF', 'ERN', 'SOS', 'AOA', 'MZN', 'ZWL', 'ZWG', 'BIF', 'RWF', 'CDF', 'XAF', 'XOF', 'XPF'], 'type': 'string'}, 'converted_amount': {'type': 'number'}, 'institution_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'masked_account_number': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}}}, 'currency': {'enum': ['USD', 'EUR', 'GBP', 'JPY', 'CHF', 'CAD', 'AUD', 'NZD', 'SEK', 'NOK', 'DKK', 'PLN', 'CZK', 'HUF', 'RON', 'BGN', 'HRK', 'ISK', 'ALL', 'BAM', 'BYN', 'MDL', 'MKD', 'RSD', 'FOK', 'GGP', 'GIP', 'IMP', 'JEP', 'CNY', 'CNH', 'KRW', 'SGD', 'HKD', 'TWD', 'THB', 'MYR', 'IDR', 'PHP', 'VND', 'INR', 'PKR', 'LKR', 'BDT', 'BND', 'BTN', 'KHR', 'LAK', 'MMK', 'MNT', 'MOP', 'MVR', 'NPR', 'KID', 'AED', 'SAR', 'QAR', 'KWD', 'BHD', 'OMR', 'JOD', 'ILS', 'EGP', 'ZAR', 'NGN', 'KES', 'GHS', 'MAD', 'TND', 'DZD', 'CVE', 'GMD', 'GNF', 'LRD', 'MGA', 'MRU', 'SHP', 'SLE', 'SLL', 'SSP', 'STN', 'YER', 'MXN', 'BRL', 'ARS', 'CLP', 'COP', 'PEN', 'UYU', 'VES', 'GTQ', 'HNL', 'NIO', 'CRC', 'PAB', 'DOP', 'JMD', 'TTD', 'BBD', 'XCD', 'ANG', 'AWG', 'BMD', 'BOB', 'BSD', 'BZD', 'CUP', 'GYD', 'HTG', 'KYD', 'PYG', 'SRD', 'XCG', 'FKP', 'FJD', 'PGK', 'SBD', 'TOP', 'TVD', 'VUV', 'WST', 'RUB', 'TRY', 'UAH', 'KZT', 'UZS', 'AZN', 'GEL', 'AMD', 'KGS', 'TJS', 'TMT', 'AFN', 'IRR', 'IQD', 'SYP', 'LBP', 'LYD', 'SDG', 'ETB', 'UGX', 'TZS', 'MWK', 'ZMW', 'BWP', 'SZL', 'LSL', 'NAD', 'MUR', 'SCR', 'KMF', 'DJF', 'ERN', 'SOS', 'AOA', 'MZN', 'ZWL', 'ZWG', 'BIF', 'RWF', 'CDF', 'XAF', 'XOF', 'XPF'], 'type': 'string'}, 'excluded': {'type': 'object', 'required': ['not_owned', 'out_of_scope_type', 'no_readable_balance', 'no_fx_rate'], 'properties': {'not_owned': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'no_fx_rate': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'out_of_scope_type': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'no_readable_balance': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}}}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which."}, 'balance_history': {'type': 'array', 'items': {'type': 'object', 'required': ['month', 'amount'], 'properties': {'month': {'type': 'string', 'pattern': '^\\d{4}-(0[1-9]|1[0-2])$'}, 'amount': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}}}}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['amount', 'currency', 'as_of', 'accounts', 'scope', 'excluded', 'partial', 'computed_by', 'success'], 'properties': {'as_of': {'type': 'string'}, 'scope': {'type': 'object', 'required': ['account_types', 'counted_unknown_ownership'], 'properties': {'account_types': {'type': 'array', 'items': {'type': 'string'}}, 'counted_unknown_ownership': {'type': 'boolean'}}, 'additionalProperties': False}, 'amount': {'type': 'number'}, 'partial': {'type': 'boolean'}, 'success': {'type': 'boolean'}, 'accounts': {'type': 'array', 'items': {'type': 'object', 'required': ['account_id', 'account_name', 'institution_name', 'masked_account_number', 'native_amount', 'native_currency', 'converted_amount', 'fx_rate'], 'properties': {'fx_rate': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'account_id': {'type': 'string', 'minLength': 1}, 'account_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'native_amount': {'type': 'number'}, 'native_currency': {'enum': ['USD', 'EUR', 'GBP', 'JPY', 'CHF', 'CAD', 'AUD', 'NZD', 'SEK', 'NOK', 'DKK', 'PLN', 'CZK', 'HUF', 'RON', 'BGN', 'HRK', 'ISK', 'ALL', 'BAM', 'BYN', 'MDL', 'MKD', 'RSD', 'FOK', 'GGP', 'GIP', 'IMP', 'JEP', 'CNY', 'CNH', 'KRW', 'SGD', 'HKD', 'TWD', 'THB', 'MYR', 'IDR', 'PHP', 'VND', 'INR', 'PKR', 'LKR', 'BDT', 'BND', 'BTN', 'KHR', 'LAK', 'MMK', 'MNT', 'MOP', 'MVR', 'NPR', 'KID', 'AED', 'SAR', 'QAR', 'KWD', 'BHD', 'OMR', 'JOD', 'ILS', 'EGP', 'ZAR', 'NGN', 'KES', 'GHS', 'MAD', 'TND', 'DZD', 'CVE', 'GMD', 'GNF', 'LRD', 'MGA', 'MRU', 'SHP', 'SLE', 'SLL', 'SSP', 'STN', 'YER', 'MXN', 'BRL', 'ARS', 'CLP', 'COP', 'PEN', 'UYU', 'VES', 'GTQ', 'HNL', 'NIO', 'CRC', 'PAB', 'DOP', 'JMD', 'TTD', 'BBD', 'XCD', 'ANG', 'AWG', 'BMD', 'BOB', 'BSD', 'BZD', 'CUP', 'GYD', 'HTG', 'KYD', 'PYG', 'SRD', 'XCG', 'FKP', 'FJD', 'PGK', 'SBD', 'TOP', 'TVD', 'VUV', 'WST', 'RUB', 'TRY', 'UAH', 'KZT', 'UZS', 'AZN', 'GEL', 'AMD', 'KGS', 'TJS', 'TMT', 'AFN', 'IRR', 'IQD', 'SYP', 'LBP', 'LYD', 'SDG', 'ETB', 'UGX', 'TZS', 'MWK', 'ZMW', 'BWP', 'SZL', 'LSL', 'NAD', 'MUR', 'SCR', 'KMF', 'DJF', 'ERN', 'SOS', 'AOA', 'MZN', 'ZWL', 'ZWG', 'BIF', 'RWF', 'CDF', 'XAF', 'XOF', 'XPF'], 'type': 'string'}, 'converted_amount': {'type': 'number'}, 'institution_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'masked_account_number': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}}, 'currency': {'type': 'string'}, 'excluded': {'type': 'object', 'required': ['not_owned', 'out_of_scope_type', 'no_readable_balance', 'no_fx_rate'], 'properties': {'not_owned': {'type': 'number'}, 'no_fx_rate': {'type': 'number'}, 'out_of_scope_type': {'type': 'number'}, 'no_readable_balance': {'type': 'number'}}, 'additionalProperties': False}, 'computed_by': {'type': 'string', 'const': 'caller'}, 'balance_history': {'type': 'array', 'items': {'type': 'object', 'required': ['month', 'amount'], 'properties': {'month': {'type': 'string'}, 'amount': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}}, 'additionalProperties': False}}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_render_cost_structure

Render a caller-computed cost structure

Put a cost breakdown YOU computed onto the cost-structure card. **This tool measures nothing.** It takes the slices and the method behind them as input and returns them for rendering. Call it only after you have computed the breakdown yourself and can state every field below from your own work, never to "get" a cost structure. The server derives no breakdown of its own. The chart draws the slices you state here, which is why every field below is required: the policy behind a grouping is the only thing that makes it checkable. **The card draws the ring, the legend and the month.** Everything else you state below is REQUIRED and reaches no pixel. All of it comes back to you in this tool's text result, which is what you write the prose from. The chart is the measure; the explanation is yours. REQUIRED, because a breakdown whose method is not stated cannot be checked: - `entries`: the slices, largest first, each a POSITIVE magnitude in `currency`. Send NO share: this tool derives every share from the amounts and returns them, and an entry carrying `pct` is refused as an unknown field. At most 4 named slices plus one rolled-up `Other`, because the card performs no rollup of its own - `period_start` and `period_end`: the INCLUSIVE bounds of the single calendar month covered. Never a quarter, never a span, never a month still running - `rung`: which grouping produced these categories. State it in prose too, so the reader knows whether they are looking at their own ledger's categories or Well's - `label_provenance`: whether a person owns those labels. A chart of accounts synced from an accounting tool is `machine`, not `curated`: the names came from the provider, not from anyone at the company - `coverage`: the outflow rows the elected grouping could label, against every outflow row the month held. This is the evidence the rung was elected on, and your prose states it - `convention` and `convention_counts`: which sign means money leaving, and the row counts you elected it from - `excluded`: what fell out, in four named groups. `no_asset_movement` is where CARD SPEND lands, because the transfer rule drops a row with no owned asset leg and a card charge moves a liability. It contains `no_owned_leg`, so never add them. Send an unmeasured LEG count as `null` rather than `0`, because zero says the rule removed nothing, and one cancelled leg count nulls all three. `unreadable_rows` is always measured and takes a number REFUSED rather than rendered: - an entry carrying `pct`, or any other field this schema does not name. The shares are DERIVED here from the amounts, so a share you send is a second opinion the card has no way to reconcile - entries out of descending-amount order, more than 4 named slices, or an `Other` slice that is not last - a negative `amount`: a breakdown is made of magnitudes - a `period_start`/`period_end` pair that is not exactly one whole calendar month, or that names a month which has not ended - `category_key` on any rung but `category_key`, or on the rolled-up `Other` slice, which is many categories and is therefore not one of them - any `label_provenance` but `unlabelled` on a rung that carries no category: `curated`, `machine` and `mixed` each claim that someone or something chose labels the chart never shows. The converse is NOT refused, because a rung elects over the month's rows while the provenance describes the ones that survived into the slices, so a labelled rung whose labelled rows all dropped is legitimately `unlabelled` - `rung: "uncategorised"` sent beside named category slices, which is a breakdown claiming to be the absence of one - `convention: "magnitude"`: that feed keeps direction in a field no grouping reaches, so no outflow was measured. `signed` elected from ZERO negative rows is the same finding, demonstrated rather than declared - coverage wider than the month it covers, or a labelled rung that could label no rows at all - one of `excluded.internal_transfers`, `excluded.no_owned_leg` and `excluded.no_asset_movement` `null` while the others are measured: one cancelled count nulls all three, and the refusal is filed against `excluded.no_asset_movement` - a `currency` outside ISO-4217: the code is checked against the catalog, not its shape An EMPTY `entries` array is accepted, and it means nothing is categorized for that month. Say that, rather than reporting zero spend: a month with no outflow at all is a different answer and the card says so differently. When the token authorizes one workspace, call this directly — no other tool call is needed first. When it authorizes several, this read will not guess which one you mean: pass `workspace_id` on the call.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['entries', 'currency', 'period_start', 'period_end', 'rung', 'label_provenance', 'coverage', 'convention', 'convention_counts', 'excluded'], 'properties': {'rung': {'enum': ['ledger_account', 'category_key', 'category_normalized', 'transaction_type', 'uncategorised'], 'type': 'string', 'description': 'Which grouping produced these categories.'}, 'entries': {'type': 'array', 'items': {'type': 'object', 'required': ['category', 'amount'], 'properties': {'amount': {'type': 'number', 'minimum': 0, 'description': "The slice's outflow, as a POSITIVE magnitude in `currency`."}, 'category': {'type': 'string', 'maxLength': 200, 'minLength': 1, 'description': "The slice's label, exactly as the reader should see it."}, 'is_other': {'type': 'boolean', 'description': 'True on the single rolled-up slice. A flag rather than a reserved label, so the rollup is a fact on the data instead of a string the server has to recognise.'}, 'category_key': {'type': 'string', 'maxLength': 200, 'minLength': 1, 'description': 'The category-catalog key this slice groups. Allowed only when `rung` is "category_key", and never on the rolled-up slice. It is the value `well_sum_transactions` accepts in `exempt_categories`, so a later exclusion names this rather than the label.'}}, 'additionalProperties': False}, 'maxItems': 5, 'description': 'The slices, largest first, with the rolled-up `Other` last when there is one.'}, 'coverage': {'type': 'object', 'required': ['labelled_rows', 'outflow_rows'], 'properties': {'outflow_rows': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0, 'description': 'Every outflow row the month held.'}, 'labelled_rows': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0, 'description': 'Outflow rows the elected grouping could label.'}}, 'description': 'The evidence the rung was elected on, so a reader can check the election rather than take it.', 'additionalProperties': False}, 'currency': {'enum': ['USD', 'EUR', 'GBP', 'JPY', 'CHF', 'CAD', 'AUD', 'NZD', 'SEK', 'NOK', 'DKK', 'PLN', 'CZK', 'HUF', 'RON', 'BGN', 'HRK', 'ISK', 'ALL', 'BAM', 'BYN', 'MDL', 'MKD', 'RSD', 'FOK', 'GGP', 'GIP', 'IMP', 'JEP', 'CNY', 'CNH', 'KRW', 'SGD', 'HKD', 'TWD', 'THB', 'MYR', 'IDR', 'PHP', 'VND', 'INR', 'PKR', 'LKR', 'BDT', 'BND', 'BTN', 'KHR', 'LAK', 'MMK', 'MNT', 'MOP', 'MVR', 'NPR', 'KID', 'AED', 'SAR', 'QAR', 'KWD', 'BHD', 'OMR', 'JOD', 'ILS', 'EGP', 'ZAR', 'NGN', 'KES', 'GHS', 'MAD', 'TND', 'DZD', 'CVE', 'GMD', 'GNF', 'LRD', 'MGA', 'MRU', 'SHP', 'SLE', 'SLL', 'SSP', 'STN', 'YER', 'MXN', 'BRL', 'ARS', 'CLP', 'COP', 'PEN', 'UYU', 'VES', 'GTQ', 'HNL', 'NIO', 'CRC', 'PAB', 'DOP', 'JMD', 'TTD', 'BBD', 'XCD', 'ANG', 'AWG', 'BMD', 'BOB', 'BSD', 'BZD', 'CUP', 'GYD', 'HTG', 'KYD', 'PYG', 'SRD', 'XCG', 'FKP', 'FJD', 'PGK', 'SBD', 'TOP', 'TVD', 'VUV', 'WST', 'RUB', 'TRY', 'UAH', 'KZT', 'UZS', 'AZN', 'GEL', 'AMD', 'KGS', 'TJS', 'TMT', 'AFN', 'IRR', 'IQD', 'SYP', 'LBP', 'LYD', 'SDG', 'ETB', 'UGX', 'TZS', 'MWK', 'ZMW', 'BWP', 'SZL', 'LSL', 'NAD', 'MUR', 'SCR', 'KMF', 'DJF', 'ERN', 'SOS', 'AOA', 'MZN', 'ZWL', 'ZWG', 'BIF', 'RWF', 'CDF', 'XAF', 'XOF', 'XPF'], 'type': 'string', 'description': 'ISO-4217 code every amount is denominated in. Checked against the catalog, not its shape.'}, 'excluded': {'type': 'object', 'required': ['internal_transfers', 'no_owned_leg', 'no_asset_movement', 'unreadable_rows'], 'properties': {'no_owned_leg': {'anyOf': [{'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, {'type': 'null'}], 'description': "The sum's `excluded_no_owned_leg`. `null` when it could not be counted, never 0."}, 'unreadable_rows': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0, 'description': 'Rows dropped for an amount or a currency that could not be read.'}, 'no_asset_movement': {'anyOf': [{'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, {'type': 'null'}], 'description': "The sum's `excluded_zero_leg`: rows the transfer rule dropped for carrying no owned ASSET leg. This is where card spend sits, because a card charge moves a liability and belongs to the later repayment. It is the widest of the three and CONTAINS `no_owned_leg`, so never add the two together. `null` when it could not be counted, never 0."}, 'internal_transfers': {'anyOf': [{'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, {'type': 'null'}], 'description': "The sum's `excluded_multi_leg`. `null` when it could not be counted, never 0."}}, 'description': 'The four exclusion groups kept apart: the transfers the rule removed, the rows with no owned asset leg (card spend), the subset of those attributable to no account at all, and the rows dropped as unreadable. Merging them hides the difference between a rule and a defect.', 'additionalProperties': False}, 'convention': {'enum': ['signed', 'magnitude'], 'type': 'string', 'description': 'Which sign the feed uses for an outflow. "magnitude" is refused: it measures no outflow.'}, 'period_end': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$', 'description': 'INCLUSIVE last day of that same month.'}, 'period_start': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$', 'description': 'INCLUSIVE first day of the month covered.'}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which."}, 'conversation_id': {'type': 'string', '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.'}, 'label_provenance': {'enum': ['curated', 'machine', 'mixed', 'unlabelled'], 'type': 'string', 'description': 'Whether a person set or confirmed the labels the reader can see.'}, 'convention_counts': {'type': 'object', 'required': ['negative', 'positive'], 'properties': {'negative': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'positive': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}}, 'description': 'The row counts the convention was elected from.', 'additionalProperties': False}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['entries', 'currency', 'period_start', 'period_end', 'rung', 'label_provenance', 'coverage', 'convention', 'convention_counts', 'excluded', 'computed_by', 'success'], 'properties': {'rung': {'type': 'string'}, 'entries': {'type': 'array', 'items': {'type': 'object', 'required': ['category', 'amount', 'pct'], 'properties': {'pct': {'type': 'number'}, 'amount': {'type': 'number'}, 'category': {'type': 'string'}, 'is_other': {'type': 'boolean'}, 'category_key': {'type': 'string'}}, 'additionalProperties': False}}, 'success': {'type': 'boolean'}, 'coverage': {'type': 'object', 'required': ['labelled_rows', 'outflow_rows'], 'properties': {'outflow_rows': {'type': 'number'}, 'labelled_rows': {'type': 'number'}}, 'additionalProperties': False}, 'currency': {'type': 'string'}, 'excluded': {'type': 'object', 'required': ['internal_transfers', 'no_owned_leg', 'no_asset_movement', 'unreadable_rows'], 'properties': {'no_owned_leg': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'unreadable_rows': {'type': 'number'}, 'no_asset_movement': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'internal_transfers': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}}, 'additionalProperties': False}, 'convention': {'type': 'string'}, 'period_end': {'type': 'string'}, 'computed_by': {'type': 'string', 'const': 'caller'}, 'period_start': {'type': 'string'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'label_provenance': {'type': 'string'}, 'convention_counts': {'type': 'object', 'required': ['negative', 'positive'], 'properties': {'negative': {'type': 'number'}, 'positive': {'type': 'number'}}, 'additionalProperties': False}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_render_mrr

Render a caller-computed recurring revenue figure

Put an MRR figure YOU computed onto the MRR card. **This tool measures nothing.** It takes the figure and its method as input and returns them for rendering. Call it only after you have computed the recurring revenue yourself and can state every field below from your own work — never to "get" an MRR. The server derives no MRR of its own. The figure on the card is the one you state here, which is why every field below is required: the policy behind a number is the only thing that makes it checkable. **Under the number the card draws nothing.** It carries the figure, the window it averages and the trend chip; everything else you state below is REQUIRED and reaches no pixel. All of it comes back in this tool's text result, which is what you write the prose from. The card is the measure; the explanation is yours. REQUIRED, because a figure whose method is not stated cannot be checked: - `amount` — the recurring revenue per month in `currency`, net of tax and of credit notes, as the sum returned it - `window` — the months the average divides by, not the months that carried revenue - `months_in_window` and `months_with_revenue` — a window with dark months reports LOWER than its typical month. When the two differ you MUST say so in prose: how many months recorded recurring revenue, and that the average still divides by the whole window - `recurring_contexts` — the billing contexts the reader confirmed as recurring, as the keys the card recorded. `"unclassified"` among them means the reader counted the invoices with no billing context (the sum rows whose `billing_context` is `null`) as recurring. This is the reader's half of the policy and the card cannot show it, so an answer that does not name them leaves the figure unchecked - `invoice_count`, `unattributed_count` and `unclassified_count` — how much of the window the figure could reach at all. `invoice_count` is the issued invoices; `unattributed_count` is the SEPARATE set Well could place on neither side, reported beside it rather than inside it, and it may be larger. An unattributed invoice may still be recurring revenue. An unclassified one carries no billing context: it is in the figure only when `recurring_contexts` holds `"unclassified"`, and when it is, say in prose that the reader chose to count it. Send `null` for a count the sum returned as `null`: it is unmeasured, not zero - `excluded` — what fell out, as three invoice COUNTS kept apart: `one_off` (issued invoices under a context the reader did not count), `credit_notes` (the `credit_note_count` netted into the figure) and `unreadable_rows` (the sum's `excluded_malformed`, `null` when unmeasured) REFUSED rather than rendered, each because your own figures disagree with each other: - a negative `amount` — the credit notes outweighed the recurring invoices, so net recurring revenue fell below zero. That is a finding to report in prose, not a figure to put on a card, and never one to flip to its magnitude - an empty `recurring_contexts` — an MRR with nothing counted as recurring is not an MRR of zero, it is a policy nobody stated. Say the figure has nothing to measure instead - `months_with_revenue` above `months_in_window`, or `unclassified_count` above `invoice_count` - a `months_in_window` that disagrees with the months `window` spans — the two state one fact - a window whose bounds are not month starts — a month-average divides by whole months - `change` with no `baseline`, a `baseline.value` of zero, a baseline that does not start before the window or spans a different number of months, or a `change` whose magnitude or sign its own two figures contradict - a `per_month` series that does not name each month of the window once in order, does not average to `amount`, or disagrees with `months_with_revenue` **Send `baseline` and `change` as a pair or send neither.** Do not send a direction: the card's colour is decided server-side from the figures. Revenue is higher-is-better, which is the opposite of the burn card and exactly why a caller does not get to state it. When the token authorizes one workspace, call this directly — no other tool call is needed first. When it authorizes several, this read will not guess which one you mean: pass `workspace_id` on the call.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['amount', 'currency', 'window', 'months_in_window', 'months_with_revenue', 'recurring_contexts', 'invoice_count', 'unattributed_count', 'unclassified_count', 'excluded'], 'properties': {'amount': {'type': 'number', 'minimum': 0, 'description': 'Recurring revenue per month, net of tax and credit notes. A negative net is refused, never flipped.'}, 'change': {'type': 'number', 'description': "Signed percentage against `baseline.value`, drawn as the card's trend chip. Send it only alongside `baseline`."}, 'window': {'type': 'object', 'required': ['from', 'to'], 'properties': {'to': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$'}, 'from': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$'}}, 'description': 'Inclusive start and EXCLUSIVE end of the averaged window, YYYY-MM-DD.'}, 'baseline': {'type': 'object', 'required': ['value', 'period'], 'properties': {'value': {'type': 'number', 'description': "The baseline window's own average. Zero is refused: a percentage against nothing is a division nobody can perform.", 'exclusiveMinimum': 0}, 'period': {'type': 'object', 'required': ['from', 'to'], 'properties': {'to': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$'}, 'from': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$'}}}}, 'description': 'The earlier window this figure is compared against. Required for `change` to render, and never rendered itself: name it in prose.'}, 'currency': {'enum': ['USD', 'EUR', 'GBP', 'JPY', 'CHF', 'CAD', 'AUD', 'NZD', 'SEK', 'NOK', 'DKK', 'PLN', 'CZK', 'HUF', 'RON', 'BGN', 'HRK', 'ISK', 'ALL', 'BAM', 'BYN', 'MDL', 'MKD', 'RSD', 'FOK', 'GGP', 'GIP', 'IMP', 'JEP', 'CNY', 'CNH', 'KRW', 'SGD', 'HKD', 'TWD', 'THB', 'MYR', 'IDR', 'PHP', 'VND', 'INR', 'PKR', 'LKR', 'BDT', 'BND', 'BTN', 'KHR', 'LAK', 'MMK', 'MNT', 'MOP', 'MVR', 'NPR', 'KID', 'AED', 'SAR', 'QAR', 'KWD', 'BHD', 'OMR', 'JOD', 'ILS', 'EGP', 'ZAR', 'NGN', 'KES', 'GHS', 'MAD', 'TND', 'DZD', 'CVE', 'GMD', 'GNF', 'LRD', 'MGA', 'MRU', 'SHP', 'SLE', 'SLL', 'SSP', 'STN', 'YER', 'MXN', 'BRL', 'ARS', 'CLP', 'COP', 'PEN', 'UYU', 'VES', 'GTQ', 'HNL', 'NIO', 'CRC', 'PAB', 'DOP', 'JMD', 'TTD', 'BBD', 'XCD', 'ANG', 'AWG', 'BMD', 'BOB', 'BSD', 'BZD', 'CUP', 'GYD', 'HTG', 'KYD', 'PYG', 'SRD', 'XCG', 'FKP', 'FJD', 'PGK', 'SBD', 'TOP', 'TVD', 'VUV', 'WST', 'RUB', 'TRY', 'UAH', 'KZT', 'UZS', 'AZN', 'GEL', 'AMD', 'KGS', 'TJS', 'TMT', 'AFN', 'IRR', 'IQD', 'SYP', 'LBP', 'LYD', 'SDG', 'ETB', 'UGX', 'TZS', 'MWK', 'ZMW', 'BWP', 'SZL', 'LSL', 'NAD', 'MUR', 'SCR', 'KMF', 'DJF', 'ERN', 'SOS', 'AOA', 'MZN', 'ZWL', 'ZWG', 'BIF', 'RWF', 'CDF', 'XAF', 'XOF', 'XPF'], 'type': 'string', 'description': 'ISO-4217 code the amount is denominated in.'}, 'excluded': {'type': 'object', 'required': ['one_off', 'credit_notes', 'unreadable_rows'], 'properties': {'one_off': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0, 'description': 'Issued invoices under a context the reader did not count.'}, 'credit_notes': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0, 'description': 'Credit notes netted into the figure.'}, 'unreadable_rows': {'anyOf': [{'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, {'type': 'null'}], 'description': 'Invoices with no readable net amount or currency. Null when unmeasured.'}}, 'description': "The three exclusion groups kept apart: the reader's choice, the structural netting, and the defective rows."}, 'per_month': {'type': 'array', 'items': {'type': 'object', 'required': ['month', 'amount'], 'properties': {'month': {'type': 'string'}, 'amount': {'type': 'number'}}}, 'description': 'The series behind the average. A month with no recurring revenue belongs in it as a zero.'}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which."}, 'invoice_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0, 'description': 'Issued invoices in the window.'}, 'conversation_id': {'type': 'string', '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.'}, 'months_in_window': {'type': 'integer', 'maximum': 9007199254740991, 'description': 'The divisor — every month in the window.', 'exclusiveMinimum': 0}, 'recurring_contexts': {'type': 'array', 'items': {'type': 'string', 'maxLength': 200, 'minLength': 1}, 'maxItems': 100, 'minItems': 1, 'description': 'The billing contexts the reader confirmed as recurring, as recorded keys; "unclassified" stands for the invoices with no billing context. At least one: an MRR counting nothing as recurring is a policy nobody stated, not a zero.'}, 'unattributed_count': {'anyOf': [{'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, {'type': 'null'}], 'description': 'Invoices Well could place on neither side: a set separate from `invoice_count`, which may be larger. Null when unmeasured.'}, 'unclassified_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0, 'description': 'Invoices carrying no billing context. In the figure only when `recurring_contexts` holds "unclassified".'}, 'months_with_revenue': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0, 'description': 'How many of those months carried any recurring revenue.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['amount', 'currency', 'window', 'months_in_window', 'months_with_revenue', 'recurring_contexts', 'invoice_count', 'unattributed_count', 'unclassified_count', 'excluded', 'computed_by', 'success'], 'properties': {'trend': {'enum': ['up', 'down', 'neutral'], 'type': 'string'}, 'amount': {'type': 'number'}, 'change': {'type': 'number'}, 'window': {'type': 'object', 'required': ['from', 'to'], 'properties': {'to': {'type': 'string'}, 'from': {'type': 'string'}}, 'additionalProperties': False}, 'success': {'type': 'boolean'}, 'baseline': {'type': 'object', 'required': ['value', 'period'], 'properties': {'value': {'type': 'number'}, 'period': {'type': 'object', 'required': ['from', 'to'], 'properties': {'to': {'type': 'string'}, 'from': {'type': 'string'}}, 'additionalProperties': False}}, 'additionalProperties': False}, 'currency': {'type': 'string'}, 'excluded': {'type': 'object', 'required': ['one_off', 'credit_notes', 'unreadable_rows'], 'properties': {'one_off': {'type': 'number'}, 'credit_notes': {'type': 'number'}, 'unreadable_rows': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}}, 'additionalProperties': False}, 'per_month': {'type': 'array', 'items': {'type': 'object', 'required': ['month', 'amount'], 'properties': {'month': {'type': 'string'}, 'amount': {'type': 'number'}}, 'additionalProperties': False}}, 'computed_by': {'type': 'string', 'const': 'caller'}, 'invoice_count': {'type': 'number'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'months_in_window': {'type': 'number'}, 'recurring_contexts': {'type': 'array', 'items': {'type': 'string'}}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'unattributed_count': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'unclassified_count': {'type': 'number'}, 'months_with_revenue': {'type': 'number'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_render_runway

Render a caller-computed runway

Put a runway YOU computed onto the runway card. **This tool measures nothing.** It takes the figure and the two numbers behind it as input and returns them for rendering. Call it only after you have computed the cash and the burn yourself — never to "get" a runway. A runway is one division, so this tool checks the one thing that can be checked: that the headline follows from the two figures you state with it. State them and it renders; state a headline they do not produce and it refuses. **Under the number the card draws nothing.** It carries the months, the moment, the burn's own window when you send one (a bare month count when you do not) and a health badge. The cash amount, the burn amount and `partial` are REQUIRED and reach no pixel. All of it comes back in this tool's text result, which is what you write the prose from, the division included. The card is the measure; the explanation is yours. REQUIRED: - `months` — months of cash left, capped at 36 - `status` — "ok", "capped", "infinite" or "insufficient_data" - `cash` — the dividend, amount and currency. SIGNED: an overdrawn workspace is negative. `null` ONLY under "insufficient_data", so a half you could not measure is reported rather than invented. - `avg_burn` — the divisor as a POSITIVE magnitude, its currency, and the `trailing_months` it averaged - `as_of` — the moment the reading is valid for - `partial` — whether the cash may be a floor (the skills' `is_floor`), because an account with no readable balance or no rate was left out of it. It never means a cut-short read: a cut-short balances read or sum stops the run before this call. OPTIONAL, and send it whenever you are sending a burn: - `window` — the months the burn averaged, inclusive start and EXCLUSIVE end, each on a month start. The card names those months instead of a bare count, so a reader can see which months the figure stands on. Without it the card can only pair the cash moment with the number of months, which reads as a window ending at that moment whatever months you actually averaged. Send NONE when `avg_burn` is `null`. The statuses carry two distinctions worth stating, because both are easy to collapse: - **Zero months is DATA when the cash is gone.** A workspace already underwater has a real runway of zero, status "ok" — not "insufficient_data", which means the inputs could not be measured at all. - **Unbounded is not the same as long.** "infinite" means the workspace is not burning; "capped" means it burns slowly enough that the figure passes the 36-month window the product reports in. REFUSED rather than rendered, each because your own figures disagree: - `months` that is not `cash ÷ avg_burn` — the division is the figure's whole claim - a cash currency that differs from the burn's; one division needs one currency - a negative `avg_burn`; it is a magnitude, so a negative one means a subtotal was re-signed - "infinite" with a non-zero burn, or a zero burn reported as anything else - "capped" whose division lands inside the window, or which reports a number other than 36 - a division past the window reported as "ok" instead of "capped" - non-positive cash reported as anything but a real zero - "insufficient_data" carrying a months figure, or a null figure under any other status - an unbounded runway reporting anything but the 36-month sentinel - an `as_of` in the future - a `window` whose bounds are not each the first of a month, or that spans no month - a `window` that spans a different number of months than `avg_burn.trailing_months` — the two state one fact, and a reader cannot tell which is the lie - a `window` sent with no burn to average — an unmeasured burn averaged no months - a `window` reaching into a month that has not ended yet - a `window` bound naming no calendar month, or an unknown key on the object When the token authorizes one workspace, call this directly — no other tool call is needed first. When it authorizes several, this read will not guess which one you mean: pass `workspace_id` on the call.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['months', 'status', 'cash', 'avg_burn', 'as_of', 'partial'], 'properties': {'cash': {'anyOf': [{'type': 'object', 'required': ['amount', 'currency'], 'properties': {'amount': {'type': 'number'}, 'currency': {'enum': ['USD', 'EUR', 'GBP', 'JPY', 'CHF', 'CAD', 'AUD', 'NZD', 'SEK', 'NOK', 'DKK', 'PLN', 'CZK', 'HUF', 'RON', 'BGN', 'HRK', 'ISK', 'ALL', 'BAM', 'BYN', 'MDL', 'MKD', 'RSD', 'FOK', 'GGP', 'GIP', 'IMP', 'JEP', 'CNY', 'CNH', 'KRW', 'SGD', 'HKD', 'TWD', 'THB', 'MYR', 'IDR', 'PHP', 'VND', 'INR', 'PKR', 'LKR', 'BDT', 'BND', 'BTN', 'KHR', 'LAK', 'MMK', 'MNT', 'MOP', 'MVR', 'NPR', 'KID', 'AED', 'SAR', 'QAR', 'KWD', 'BHD', 'OMR', 'JOD', 'ILS', 'EGP', 'ZAR', 'NGN', 'KES', 'GHS', 'MAD', 'TND', 'DZD', 'CVE', 'GMD', 'GNF', 'LRD', 'MGA', 'MRU', 'SHP', 'SLE', 'SLL', 'SSP', 'STN', 'YER', 'MXN', 'BRL', 'ARS', 'CLP', 'COP', 'PEN', 'UYU', 'VES', 'GTQ', 'HNL', 'NIO', 'CRC', 'PAB', 'DOP', 'JMD', 'TTD', 'BBD', 'XCD', 'ANG', 'AWG', 'BMD', 'BOB', 'BSD', 'BZD', 'CUP', 'GYD', 'HTG', 'KYD', 'PYG', 'SRD', 'XCG', 'FKP', 'FJD', 'PGK', 'SBD', 'TOP', 'TVD', 'VUV', 'WST', 'RUB', 'TRY', 'UAH', 'KZT', 'UZS', 'AZN', 'GEL', 'AMD', 'KGS', 'TJS', 'TMT', 'AFN', 'IRR', 'IQD', 'SYP', 'LBP', 'LYD', 'SDG', 'ETB', 'UGX', 'TZS', 'MWK', 'ZMW', 'BWP', 'SZL', 'LSL', 'NAD', 'MUR', 'SCR', 'KMF', 'DJF', 'ERN', 'SOS', 'AOA', 'MZN', 'ZWL', 'ZWG', 'BIF', 'RWF', 'CDF', 'XAF', 'XOF', 'XPF'], 'type': 'string'}}}, {'type': 'null'}]}, 'as_of': {'type': 'string', 'format': 'date-time', 'pattern': '^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$'}, 'months': {'type': 'number', 'maximum': 36, 'minimum': 0}, 'status': {'enum': ['ok', 'capped', 'infinite', 'insufficient_data'], 'type': 'string'}, 'window': {'type': 'object', 'required': ['from', 'to'], 'properties': {'to': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$'}, 'from': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$'}}, 'description': 'Inclusive start and EXCLUSIVE end of the months the burn averaged, YYYY-MM-DD.', 'additionalProperties': False}, 'partial': {'type': 'boolean'}, 'avg_burn': {'anyOf': [{'type': 'object', 'required': ['amount', 'currency', 'trailing_months'], 'properties': {'amount': {'type': 'number'}, 'currency': {'enum': ['USD', 'EUR', 'GBP', 'JPY', 'CHF', 'CAD', 'AUD', 'NZD', 'SEK', 'NOK', 'DKK', 'PLN', 'CZK', 'HUF', 'RON', 'BGN', 'HRK', 'ISK', 'ALL', 'BAM', 'BYN', 'MDL', 'MKD', 'RSD', 'FOK', 'GGP', 'GIP', 'IMP', 'JEP', 'CNY', 'CNH', 'KRW', 'SGD', 'HKD', 'TWD', 'THB', 'MYR', 'IDR', 'PHP', 'VND', 'INR', 'PKR', 'LKR', 'BDT', 'BND', 'BTN', 'KHR', 'LAK', 'MMK', 'MNT', 'MOP', 'MVR', 'NPR', 'KID', 'AED', 'SAR', 'QAR', 'KWD', 'BHD', 'OMR', 'JOD', 'ILS', 'EGP', 'ZAR', 'NGN', 'KES', 'GHS', 'MAD', 'TND', 'DZD', 'CVE', 'GMD', 'GNF', 'LRD', 'MGA', 'MRU', 'SHP', 'SLE', 'SLL', 'SSP', 'STN', 'YER', 'MXN', 'BRL', 'ARS', 'CLP', 'COP', 'PEN', 'UYU', 'VES', 'GTQ', 'HNL', 'NIO', 'CRC', 'PAB', 'DOP', 'JMD', 'TTD', 'BBD', 'XCD', 'ANG', 'AWG', 'BMD', 'BOB', 'BSD', 'BZD', 'CUP', 'GYD', 'HTG', 'KYD', 'PYG', 'SRD', 'XCG', 'FKP', 'FJD', 'PGK', 'SBD', 'TOP', 'TVD', 'VUV', 'WST', 'RUB', 'TRY', 'UAH', 'KZT', 'UZS', 'AZN', 'GEL', 'AMD', 'KGS', 'TJS', 'TMT', 'AFN', 'IRR', 'IQD', 'SYP', 'LBP', 'LYD', 'SDG', 'ETB', 'UGX', 'TZS', 'MWK', 'ZMW', 'BWP', 'SZL', 'LSL', 'NAD', 'MUR', 'SCR', 'KMF', 'DJF', 'ERN', 'SOS', 'AOA', 'MZN', 'ZWL', 'ZWG', 'BIF', 'RWF', 'CDF', 'XAF', 'XOF', 'XPF'], 'type': 'string'}, 'trailing_months': {'type': 'integer', 'maximum': 9007199254740991, 'exclusiveMinimum': 0}}}, {'type': 'null'}]}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which."}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['months', 'status', 'cash', 'avg_burn', 'as_of', 'partial', 'computed_by', 'success'], 'properties': {'cash': {'anyOf': [{'type': 'object', 'required': ['amount', 'currency'], 'properties': {'amount': {'type': 'number'}, 'currency': {'enum': ['USD', 'EUR', 'GBP', 'JPY', 'CHF', 'CAD', 'AUD', 'NZD', 'SEK', 'NOK', 'DKK', 'PLN', 'CZK', 'HUF', 'RON', 'BGN', 'HRK', 'ISK', 'ALL', 'BAM', 'BYN', 'MDL', 'MKD', 'RSD', 'FOK', 'GGP', 'GIP', 'IMP', 'JEP', 'CNY', 'CNH', 'KRW', 'SGD', 'HKD', 'TWD', 'THB', 'MYR', 'IDR', 'PHP', 'VND', 'INR', 'PKR', 'LKR', 'BDT', 'BND', 'BTN', 'KHR', 'LAK', 'MMK', 'MNT', 'MOP', 'MVR', 'NPR', 'KID', 'AED', 'SAR', 'QAR', 'KWD', 'BHD', 'OMR', 'JOD', 'ILS', 'EGP', 'ZAR', 'NGN', 'KES', 'GHS', 'MAD', 'TND', 'DZD', 'CVE', 'GMD', 'GNF', 'LRD', 'MGA', 'MRU', 'SHP', 'SLE', 'SLL', 'SSP', 'STN', 'YER', 'MXN', 'BRL', 'ARS', 'CLP', 'COP', 'PEN', 'UYU', 'VES', 'GTQ', 'HNL', 'NIO', 'CRC', 'PAB', 'DOP', 'JMD', 'TTD', 'BBD', 'XCD', 'ANG', 'AWG', 'BMD', 'BOB', 'BSD', 'BZD', 'CUP', 'GYD', 'HTG', 'KYD', 'PYG', 'SRD', 'XCG', 'FKP', 'FJD', 'PGK', 'SBD', 'TOP', 'TVD', 'VUV', 'WST', 'RUB', 'TRY', 'UAH', 'KZT', 'UZS', 'AZN', 'GEL', 'AMD', 'KGS', 'TJS', 'TMT', 'AFN', 'IRR', 'IQD', 'SYP', 'LBP', 'LYD', 'SDG', 'ETB', 'UGX', 'TZS', 'MWK', 'ZMW', 'BWP', 'SZL', 'LSL', 'NAD', 'MUR', 'SCR', 'KMF', 'DJF', 'ERN', 'SOS', 'AOA', 'MZN', 'ZWL', 'ZWG', 'BIF', 'RWF', 'CDF', 'XAF', 'XOF', 'XPF'], 'type': 'string'}}, 'additionalProperties': False}, {'type': 'null'}]}, 'as_of': {'type': 'string'}, 'months': {'type': 'number'}, 'status': {'type': 'string'}, 'window': {'type': 'object', 'required': ['from', 'to'], 'properties': {'to': {'type': 'string'}, 'from': {'type': 'string'}}, 'additionalProperties': False}, 'partial': {'type': 'boolean'}, 'success': {'type': 'boolean'}, 'avg_burn': {'anyOf': [{'type': 'object', 'required': ['amount', 'currency', 'trailing_months'], 'properties': {'amount': {'type': 'number'}, 'currency': {'enum': ['USD', 'EUR', 'GBP', 'JPY', 'CHF', 'CAD', 'AUD', 'NZD', 'SEK', 'NOK', 'DKK', 'PLN', 'CZK', 'HUF', 'RON', 'BGN', 'HRK', 'ISK', 'ALL', 'BAM', 'BYN', 'MDL', 'MKD', 'RSD', 'FOK', 'GGP', 'GIP', 'IMP', 'JEP', 'CNY', 'CNH', 'KRW', 'SGD', 'HKD', 'TWD', 'THB', 'MYR', 'IDR', 'PHP', 'VND', 'INR', 'PKR', 'LKR', 'BDT', 'BND', 'BTN', 'KHR', 'LAK', 'MMK', 'MNT', 'MOP', 'MVR', 'NPR', 'KID', 'AED', 'SAR', 'QAR', 'KWD', 'BHD', 'OMR', 'JOD', 'ILS', 'EGP', 'ZAR', 'NGN', 'KES', 'GHS', 'MAD', 'TND', 'DZD', 'CVE', 'GMD', 'GNF', 'LRD', 'MGA', 'MRU', 'SHP', 'SLE', 'SLL', 'SSP', 'STN', 'YER', 'MXN', 'BRL', 'ARS', 'CLP', 'COP', 'PEN', 'UYU', 'VES', 'GTQ', 'HNL', 'NIO', 'CRC', 'PAB', 'DOP', 'JMD', 'TTD', 'BBD', 'XCD', 'ANG', 'AWG', 'BMD', 'BOB', 'BSD', 'BZD', 'CUP', 'GYD', 'HTG', 'KYD', 'PYG', 'SRD', 'XCG', 'FKP', 'FJD', 'PGK', 'SBD', 'TOP', 'TVD', 'VUV', 'WST', 'RUB', 'TRY', 'UAH', 'KZT', 'UZS', 'AZN', 'GEL', 'AMD', 'KGS', 'TJS', 'TMT', 'AFN', 'IRR', 'IQD', 'SYP', 'LBP', 'LYD', 'SDG', 'ETB', 'UGX', 'TZS', 'MWK', 'ZMW', 'BWP', 'SZL', 'LSL', 'NAD', 'MUR', 'SCR', 'KMF', 'DJF', 'ERN', 'SOS', 'AOA', 'MZN', 'ZWL', 'ZWG', 'BIF', 'RWF', 'CDF', 'XAF', 'XOF', 'XPF'], 'type': 'string'}, 'trailing_months': {'type': 'number'}}, 'additionalProperties': False}, {'type': 'null'}]}, 'computed_by': {'type': 'string', 'const': 'caller'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_repost_journals

Re-trigger posting

Re-run (repost) the posting for this fiscal period's ready rows — the workspace's re-triggerable posting gap. This is the ACTION that books the rows `well_list_unposted_journals` lists as ready to post: when the accounting is ready and simply has not posted, calling this re-runs the deterministic posters and clears it. It operates on the ALREADY-RESOLVED workspace and takes no arguments — do not list or switch workspaces first. This is NOT `well_list_workspaces` (which only enumerates workspaces and posts nothing), and NOT `well_set_transaction_ledger_account` (which assigns an account to ONE row that is MISSING one). This tool posts rows that already have everything they need; it never assigns an account or picks a category. Do NOT call this while `in_flight_processing` is true — Well is still processing the rows (enrichment in flight); wait and re-read instead. Do NOT call it to fix a row that needs a category, a ledger account, or a party decision — those are substantive halts a retry only re-fails, and `well_list_unposted_journals` never lists them. The re-run is workspace-scoped and idempotent: it re-posts the whole re-triggerable set, and the posters skip anything already booked, so a repeated press is safe. It returns `enqueued` (rows that reached their poster) and `skipped` (each row that did not, with a reason). When the token authorizes one workspace, call this directly — no other tool call is needed first. When it authorizes several, this read will not guess which one you mean: pass `workspace_id` on the call.

Idempotent

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.'}, 'conversation_id': {'type': 'string', '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.'}, 'idempotency_key': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success', 'enqueued', 'skipped'], 'properties': {'error': {'type': 'string'}, 'skipped': {'type': 'array', 'items': {'type': 'object', 'required': ['source_id', 'source_kind', 'reason'], 'properties': {'reason': {'type': 'string'}, 'source_id': {'type': 'string'}, 'source_kind': {'type': 'string'}}, 'additionalProperties': False}}, 'success': {'type': 'boolean'}, 'enqueued': {'type': 'number'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_resolve_reconciliation_task

Resolve reconciliation task

Approve or reject one or more reconciliation review tasks (from well_run_register_diff or the in-app review queue). - approve: confirms the match — the link is flipped to active. - reject: dismisses the match — the candidate does not silently re-surface. Each task_id resolves independently; a failure on one (already resolved, not found) is returned in errors and does not block the rest of the batch.

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['task_ids', 'action'], 'properties': {'action': {'enum': ['approve', 'reject'], 'type': 'string'}, 'task_ids': {'type': 'array', 'items': {'type': 'string', 'minLength': 1}, 'maxItems': 100, 'minItems': 1, 'description': "The review tasks' task_id values."}, 'selection': {'type': 'object', 'required': ['target_type', 'target_id', 'allocated_amount'], 'properties': {'target_id': {'type': 'string', '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)$'}, 'target_type': {'type': 'string', 'const': 'transaction'}, 'allocated_amount': {'type': 'number', 'description': 'The invoice-currency amount this settlement covers.', 'exclusiveMinimum': 0}}, 'description': 'For an unresolved reconciliation review task: the transaction the reviewer picked to settle the invoice. Applies to exactly one task; required on approve, rejected elsewhere.'}, 'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.'}, 'conversation_id': {'type': 'string', '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.'}, 'idempotency_key': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'error': {'type': 'string'}, 'errors': {'type': 'array', 'items': {'type': 'object', 'required': ['task_id', 'error'], 'properties': {'error': {'type': 'string'}, 'task_id': {'type': 'string'}}, 'additionalProperties': False}}, 'success': {'type': 'boolean'}, 'resolved': {'type': 'array', 'items': {'type': 'object', 'required': ['task_id', 'action', 'success'], 'properties': {'action': {'type': 'string'}, 'success': {'type': 'boolean'}, 'task_id': {'type': 'string'}}, 'additionalProperties': False}}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_resolve_register_diff_gap

Resolve register diff gap

Post a well_run_register_diff gap (one of missing_in_register_ids' review tasks) into QuickBooks as a Purchase or Deposit. Requires the exact ledger_account_id (a UUID, not a name) for both: - bank_ledger_account_id: the bank/cash account the money moved through (e.g. Checking). - category_ledger_account_id: the expense or income category the gap books against. Look these up first with well_query_records({ root: "ledger_accounts", filters: [...] }) scoped to the register connector — never guess an id or match an account by substring/fuzzy name. Fails with an error (not a silent no-op) if gap posting is disabled for this workspace, if either account doesn't belong to this gap's register connector, or if either account no longer resolves in QuickBooks.

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['task_id', 'bank_ledger_account_id', 'category_ledger_account_id'], 'properties': {'task_id': {'type': 'string', 'minLength': 1, 'description': "The gap review task's task_id."}, 'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.'}, 'conversation_id': {'type': 'string', '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.'}, 'idempotency_key': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.'}, 'bank_ledger_account_id': {'type': 'string', 'minLength': 1, 'description': 'ledger_account_id of the bank/cash account.'}, 'category_ledger_account_id': {'type': 'string', 'minLength': 1, 'description': 'ledger_account_id of the category account.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'error': {'type': 'string'}, 'success': {'type': 'boolean'}, 'task_id': {'type': 'string'}, 'external_id': {'type': 'string'}, 'already_posted': {'type': 'boolean'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_retarget_connectors

Retarget connectors

Retarget (bring across) ledger connectors from this workspace's lineage parent onto this workspace — the write behind the connector-retarget card. For each source connector, a new connector row is created here that borrows the parent's credentials and pulls the item's history in on its own first sync; the transactions are not moved. REQUIRED: source_workspace_connector_ids — the workspace_connector_id of each candidate to bring across, from well_list_retargetable_connectors or well_show_retargetable_connectors. An id that is not a current candidate here is refused; an id whose connector has already been retargeted is reported back under already_retargeted_workspace_connector_ids rather than erroring, so a repeated Confirm is a safe replay. Only a workspace owner or admin may retarget a connector, and the acting person must also hold an active membership on the parent workspace whose credentials the borrow consumes. A caller without that role or that membership is refused, not silently ignored.

Idempotent

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['source_workspace_connector_ids'], 'properties': {'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.'}, 'conversation_id': {'type': 'string', '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.'}, 'idempotency_key': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.'}, 'source_workspace_connector_ids': {'type': 'array', 'items': {'type': 'string', '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)$'}, 'minItems': 1, 'description': 'The workspace_connector_id of each parent connector to bring across, copied from well_list_retargetable_connectors or well_show_retargetable_connectors.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'error': {'type': 'string'}, 'success': {'type': 'boolean'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}, 'created_workspace_connector_ids': {'type': 'array', 'items': {'type': 'string', '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)$'}, 'description': 'The connector rows created on this workspace, one per newly retargeted source.'}, 'already_retargeted_workspace_connector_ids': {'type': 'array', 'items': {'type': 'string', '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)$'}, 'description': 'Source ids that had already been retargeted — an expected replay, not an error.'}}, 'additionalProperties': False}

well_run_register_diff

Run register diff

Diff a workspace's bank transactions against its accounting-register transactions (e.g. QuickBooks), and persist the result. - Every match — hard evidence (structured reference, IBAN, tax ID) or inference-only (memo/payee reading) — is raised as a review task with the candidate already attached (raised_for_review). Nothing links automatically; resolve with well_resolve_reconciliation_task once a human decides. - Bank transactions with no register counterpart come back as missing_in_register_ids, each also minted as a gap review task (gaps_proposed) — resolve one with well_resolve_register_diff_gap once a human names the two ledger accounts. gaps_already_proposed counts gaps re-surfaced from an earlier run that already have an open, unresolved proposal. - Bank transactions NOT confirmed absent from the register come back as contended_in_register_ids — never minted as a gap. Two cases land here: (1) a plausible match lost to a higher-confidence sibling transaction this run, so the register-side movement is already accounted for by the winner; (2) the matcher couldn't produce a trustworthy answer (an invalid model response or a provider failure), so absence was never confirmed. Re-run the diff later; a genuine gap or duplicate should resolve itself once the winner's review task is handled or the matcher succeeds. - Register entries no bank transaction explains come back as unexplained_in_register_ids. Returns { enabled: false, ... } with all counts 0 if the workspace's register-diff feature is off.

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['bank_workspace_connector_id', 'register_workspace_connector_id'], 'properties': {'since_date': {'type': 'string', 'description': 'Only diff bank transactions on/after this date (YYYY-MM-DD).'}, 'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.'}, 'conversation_id': {'type': 'string', '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.'}, 'idempotency_key': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.'}, 'bank_workspace_connector_id': {'type': 'string', 'minLength': 1, 'description': "The bank connector's workspace_connector_id (e.g. Plaid)."}, 'register_workspace_connector_id': {'type': 'string', 'minLength': 1, 'description': "The accounting connector's workspace_connector_id (e.g. QuickBooks)."}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'error': {'type': 'string'}, 'enabled': {'type': 'boolean'}, 'matched': {'type': 'number'}, 'success': {'type': 'boolean'}, 'gaps_proposed': {'type': 'number'}, 'already_linked': {'type': 'number'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'raised_for_review': {'type': 'number'}, 'missing_in_register': {'type': 'number'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'contended_in_register': {'type': 'number'}, 'gaps_already_proposed': {'type': 'number'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}, 'missing_in_register_ids': {'type': 'array', 'items': {'type': 'string'}}, 'unexplained_in_register': {'type': 'number'}, 'contended_in_register_ids': {'type': 'array', 'items': {'type': 'string'}}, 'unexplained_in_register_ids': {'type': 'array', 'items': {'type': 'string'}}}, 'additionalProperties': False}

well_search_company_registry

Search the company registry

Search the public company registries for a company by name, to find the one a workspace IS before you create its company workspace. This draws nothing on the user's screen. Use it in the zero-company case: a membership workspace has no company attached and no detected candidate, so you search the registry for the user's company. Each hit carries an `id` — the registry ref — that you pass to well_create_company_candidate as `registry_ref` to mint a candidate from that hit, then well_create_company_workspace to make it the company workspace. Pass `country` when the user names one, to scope the search to that jurisdiction. The result carries `degraded: true` when a provider was unreachable and the hits are partial. Confirm the exact company with the user before you create anything from a hit; never pick one from a name alone.

Read only Open world

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['q'], 'properties': {'q': {'type': 'string', 'maxLength': 200, 'minLength': 2, 'description': 'The company name to search for. At least 2 characters.'}, 'country': {'enum': ['AD', 'AE', 'AF', 'AG', 'AI', 'AL', 'AM', 'AO', 'AQ', 'AR', 'AS', 'AT', 'AU', 'AW', 'AX', 'AZ', 'BA', 'BB', 'BD', 'BE', 'BF', 'BG', 'BH', 'BI', 'BJ', 'BL', 'BM', 'BN', 'BO', 'BQ', 'BR', 'BS', 'BT', 'BV', 'BW', 'BY', 'BZ', 'CA', 'CC', 'CD', 'CF', 'CG', 'CH', 'CI', 'CK', 'CL', 'CM', 'CN', 'CO', 'CR', 'CU', 'CV', 'CW', 'CX', 'CY', 'CZ', 'DE', 'DJ', 'DK', 'DM', 'DO', 'DZ', 'EC', 'EE', 'EG', 'EH', 'ER', 'ES', 'ET', 'FI', 'FJ', 'FK', 'FM', 'FO', 'FR', 'GA', 'GB', 'GD', 'GE', 'GF', 'GG', 'GH', 'GI', 'GL', 'GM', 'GN', 'GP', 'GQ', 'GR', 'GS', 'GT', 'GU', 'GW', 'GY', 'HK', 'HM', 'HN', 'HR', 'HT', 'HU', 'ID', 'IE', 'IL', 'IM', 'IN', 'IO', 'IQ', 'IR', 'IS', 'IT', 'JE', 'JM', 'JO', 'JP', 'KE', 'KG', 'KH', 'KI', 'KM', 'KN', 'KP', 'KR', 'KW', 'KY', 'KZ', 'LA', 'LB', 'LC', 'LI', 'LK', 'LR', 'LS', 'LT', 'LU', 'LV', 'LY', 'MA', 'MC', 'MD', 'ME', 'MF', 'MG', 'MH', 'MK', 'ML', 'MM', 'MN', 'MO', 'MP', 'MQ', 'MR', 'MS', 'MT', 'MU', 'MV', 'MW', 'MX', 'MY', 'MZ', 'NA', 'NC', 'NE', 'NF', 'NG', 'NI', 'NL', 'NO', 'NP', 'NR', 'NU', 'NZ', 'OM', 'PA', 'PE', 'PF', 'PG', 'PH', 'PK', 'PL', 'PM', 'PN', 'PR', 'PS', 'PT', 'PW', 'PY', 'QA', 'RE', 'RO', 'RS', 'RU', 'RW', 'SA', 'SB', 'SC', 'SD', 'SE', 'SG', 'SH', 'SI', 'SJ', 'SK', 'SL', 'SM', 'SN', 'SO', 'SR', 'SS', 'ST', 'SV', 'SX', 'SY', 'SZ', 'TC', 'TD', 'TF', 'TG', 'TH', 'TJ', 'TK', 'TL', 'TM', 'TN', 'TO', 'TR', 'TT', 'TV', 'TW', 'TZ', 'UA', 'UG', 'UM', 'US', 'UY', 'UZ', 'VA', 'VC', 'VE', 'VG', 'VI', 'VN', 'VU', 'WF', 'WS', 'YE', 'YT', 'ZA', 'ZM', 'ZW'], 'type': 'string', 'description': 'Scope the search to this jurisdiction. Omit to search across registries.'}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Optional: this tool describes the token itself rather than one workspace's data, so omitting it returns the same answer."}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['hits', 'degraded', 'success'], 'properties': {'hits': {'type': 'array', 'items': {'type': 'object', 'required': ['type', 'id', 'attributes'], 'properties': {'id': {'type': 'string'}, 'type': {'type': 'string', 'const': 'company-registry-hit'}, 'attributes': {'type': 'object', 'required': ['provider', 'legal_name', 'trade_name', 'siren', 'siret', 'vat_number', 'vat_number_derived', 'unverified_vat_number', 'registry_number', 'legal_form', 'business_type', 'country', 'fiscal_year_start_month', 'address_text', 'source_url', 'website'], 'properties': {'siren': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'siret': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'country': {'anyOf': [{'enum': ['AD', 'AE', 'AF', 'AG', 'AI', 'AL', 'AM', 'AO', 'AQ', 'AR', 'AS', 'AT', 'AU', 'AW', 'AX', 'AZ', 'BA', 'BB', 'BD', 'BE', 'BF', 'BG', 'BH', 'BI', 'BJ', 'BL', 'BM', 'BN', 'BO', 'BQ', 'BR', 'BS', 'BT', 'BV', 'BW', 'BY', 'BZ', 'CA', 'CC', 'CD', 'CF', 'CG', 'CH', 'CI', 'CK', 'CL', 'CM', 'CN', 'CO', 'CR', 'CU', 'CV', 'CW', 'CX', 'CY', 'CZ', 'DE', 'DJ', 'DK', 'DM', 'DO', 'DZ', 'EC', 'EE', 'EG', 'EH', 'ER', 'ES', 'ET', 'FI', 'FJ', 'FK', 'FM', 'FO', 'FR', 'GA', 'GB', 'GD', 'GE', 'GF', 'GG', 'GH', 'GI', 'GL', 'GM', 'GN', 'GP', 'GQ', 'GR', 'GS', 'GT', 'GU', 'GW', 'GY', 'HK', 'HM', 'HN', 'HR', 'HT', 'HU', 'ID', 'IE', 'IL', 'IM', 'IN', 'IO', 'IQ', 'IR', 'IS', 'IT', 'JE', 'JM', 'JO', 'JP', 'KE', 'KG', 'KH', 'KI', 'KM', 'KN', 'KP', 'KR', 'KW', 'KY', 'KZ', 'LA', 'LB', 'LC', 'LI', 'LK', 'LR', 'LS', 'LT', 'LU', 'LV', 'LY', 'MA', 'MC', 'MD', 'ME', 'MF', 'MG', 'MH', 'MK', 'ML', 'MM', 'MN', 'MO', 'MP', 'MQ', 'MR', 'MS', 'MT', 'MU', 'MV', 'MW', 'MX', 'MY', 'MZ', 'NA', 'NC', 'NE', 'NF', 'NG', 'NI', 'NL', 'NO', 'NP', 'NR', 'NU', 'NZ', 'OM', 'PA', 'PE', 'PF', 'PG', 'PH', 'PK', 'PL', 'PM', 'PN', 'PR', 'PS', 'PT', 'PW', 'PY', 'QA', 'RE', 'RO', 'RS', 'RU', 'RW', 'SA', 'SB', 'SC', 'SD', 'SE', 'SG', 'SH', 'SI', 'SJ', 'SK', 'SL', 'SM', 'SN', 'SO', 'SR', 'SS', 'ST', 'SV', 'SX', 'SY', 'SZ', 'TC', 'TD', 'TF', 'TG', 'TH', 'TJ', 'TK', 'TL', 'TM', 'TN', 'TO', 'TR', 'TT', 'TV', 'TW', 'TZ', 'UA', 'UG', 'UM', 'US', 'UY', 'UZ', 'VA', 'VC', 'VE', 'VG', 'VI', 'VN', 'VU', 'WF', 'WS', 'YE', 'YT', 'ZA', 'ZM', 'ZW'], 'type': 'string'}, {'type': 'null'}]}, 'website': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'provider': {'enum': ['RECHERCHE_ENTREPRISES', 'PAPPERS', 'OPENCORPORATES', 'EXA', 'EXA_ANSWER'], 'type': 'string'}, 'legal_form': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'legal_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'source_url': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'trade_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'vat_number': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'address_text': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'business_type': {'anyOf': [{'enum': ['Inc', 'Corp', 'LLC', 'LLP', 'LP', 'LLLP', 'PC', 'PLLC', 'PLC', 'Co', 'Ltd', 'DBA', 'Partnership', 'Sole_Proprietorship', 'C-Corp', 'S-Corp', 'B-Corp', 'PBC', 'CIC', 'CIO', 'IPS', 'EEIG', 'Sole_Trader', 'Unlimited', 'REIT', 'GmbH', 'AG', 'UG', 'OHG', 'GbR', 'PartG', 'eG', 'KGaA', 'GmbH_Co_KG', 'Einzelunternehmen', 'PartGmbB', 'SARL', 'SA', 'SAS', 'SASU', 'EURL', 'SNC', 'SCS', 'SCA', 'SEP', 'GIE', 'GEIE', 'SCOP', 'Auto_Entrepreneur', 'EI', 'EIRL', 'SpA', 'SRL', 'SNC_IT', 'SAS_IT', 'SAPA', 'SC', 'Ditta_Individuale', 'STP', 'Startup_Innovativa', 'SL', 'SC_ES', 'Scom', 'SCom_A', 'SCOOP', 'AIE', 'UTE', 'Empresario_Individual', 'CB', 'SAT', 'BV', 'NV', 'VOF', 'CV', 'Maatschap', 'VvE', 'Stichting', 'Vereniging', 'Coöperatie', 'EESV', 'Eenmanszaak', 'SPRL', 'SRL_BE', 'SCRL', 'Entreprise_Individuelle', 'ASBL', 'Sàrl', 'Kollektivgesellschaft', 'Kommanditgesellschaft', 'Einzelfirma', 'Genossenschaft', 'Verein', 'Stiftung', 'Kommanditaktiengesellschaft', 'OG', 'Gen', 'Stille_Gesellschaft', 'EWIV', 'Ltée', 'ULC', 'Cooperative_CA', 'NPO', 'Pty_Ltd', 'Trust', 'Co-operative', 'Incorporated_Association', 'CCIV', 'AMIT', 'KK', 'GK', 'YK', 'Gomei', 'Goshi', 'TMK', 'Cooperative_JP', 'Pvt_Ltd', 'HUF', 'Section_8', 'Producer_Company', 'OPC', 'Cooperative_IN', 'Trust_IN', 'Society', 'JSC', 'WFOE', 'JV', 'Rep_Office', 'FIE', 'Cooperative_CN', 'Ltda', 'Eireli', 'MEI', 'LTDA_ME', 'EPP', 'Cooperativa', 'SCP', 'Empresario_Individual_BR', 'SC_MX', 'SCS_MX', 'SCA_MX', 'SAPI', 'SAS_MX', 'Persona_Fisica', 'SOFOM', 'Pte_Ltd', 'Branch', 'Society_SG', 'Cooperative_SG', 'Branch_HK', 'Rep_Office_HK', 'Trust_HK', 'Cooperative_HK', 'Co_Ltd', 'Branch_KR', 'Rep_Office_KR', 'OAO', 'ZAO', 'OOO', 'PAO', 'AO', 'IP', 'GP_RU', 'Production_Cooperative', 'CC', 'NPO_ZA', 'NPC', 'PJSC', 'PJSCC', 'Branch_AE', 'Rep_Office_AE', 'Civil_Company', 'Free_Zone', 'JSC_SA', 'GP_SA', 'LPS', 'Branch_SA', 'Professional_Company', 'Other', 'Unknown', 'Corporation', 'Company', 'Enterprise', 'Firm', 'Business'], 'type': 'string'}, {'type': 'null'}]}, 'registry_number': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'vat_number_derived': {'type': 'boolean'}, 'unverified_vat_number': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'fiscal_year_start_month': {'anyOf': [{'type': 'integer', 'maximum': 12, 'minimum': 1}, {'type': 'null'}]}}, 'additionalProperties': False}}, 'additionalProperties': False}}, 'error': {'type': 'string'}, 'success': {'type': 'boolean'}, 'degraded': {'type': 'boolean', 'description': 'True when a registry provider was unreachable and the hits are partial; the search still returned what it could.'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_search_context

Search context

Search the workspace's recorded notes and context (meeting notes, tickets, imported documents) for a query. Returns compact snippets — each result's "snippets" is an array of one or more matched passages from that note, never the full note body — follow up with well_get_entity on the returned note id for the full record. Use this for questions about the business, a company, a person, a process, pricing, or a past decision. Do NOT use this for a question well_query_records already answers (amounts, counts, lists, filters). When the token authorizes one workspace, call this directly — no other tool call is needed first. When it authorizes several, this read will not guess which one you mean: pass `workspace_id` on the call.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['query'], 'properties': {'topK': {'type': 'integer', 'default': 10, 'maximum': 25, 'minimum': 1}, 'query': {'type': 'string', 'maxLength': 500, 'minLength': 1, 'description': "Focused search query over the workspace's recorded notes and context."}, 'category': {'type': 'string'}, 'entityId': {'type': 'string', '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)$'}, 'entityType': {'enum': ['note'], 'type': 'string'}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which."}, 'occurredAfter': {'type': 'string', 'format': 'date-time', 'pattern': '^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$'}, 'occurredBefore': {'type': 'string', 'format': 'date-time', 'pattern': '^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$'}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['results', 'total_returned', 'success'], 'properties': {'error': {'type': 'string'}, 'results': {'type': 'array', 'items': {'type': 'object', 'required': ['note_id', 'title', 'snippets', 'source_url', 'occurred_at'], 'properties': {'title': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'note_id': {'type': 'string'}, 'snippets': {'type': 'array', 'items': {'type': 'object', 'required': ['passage'], 'properties': {'passage': {'type': 'string'}}, 'additionalProperties': False}}, 'source_url': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'occurred_at': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}}, 'success': {'type': 'boolean'}, 'total_returned': {'type': 'number'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_search_skill

Search skill

Find the Well procedure for what the user wants to do, when no Well skill is installed in this conversation. Returns the roster of Well skills with their descriptions; pick the one whose description matches the request, then call well_get_skill with its id and follow the returned instructions exactly. Call this FIRST for any request that asks to DO a finance job with Well — fetch or chase missing invoices, connect a bank or a tool, pick a period, categorize suppliers. Route on the form of the request: a job to carry out ("go chase", "get them collected", "connect", "categorize before I close") comes here, while a question about the state of the data ("what is", "which", "how many", "show me", "preview") goes to the matching well_* read tool. Never call it for a question about the user's data (a cash figure, a runway, a list of records, a period's status): those go straight to the matching well_* read tool. Do not call it when a Well skill is already loaded in the conversation.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'query': {'type': 'string', 'pattern': '^[^\\n\\r]*$', 'maxLength': 200, 'description': 'What the user wants to do, in their own terms. The whole roster is returned either way.'}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Optional: this tool describes the token itself rather than one workspace's data, so omitting it returns the same answer."}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success', 'reason', 'skills'], 'properties': {'error': {'type': 'string'}, 'reason': {'anyOf': [{'enum': ['skill_unknown', 'catalog_unreadable', 'write_skill_in_app'], 'type': 'string'}, {'type': 'null'}]}, 'skills': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'description'], 'properties': {'id': {'type': 'string'}, 'description': {'type': 'string'}}, 'additionalProperties': False}}, 'success': {'type': 'boolean'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_set_counterparty_default_category

Declare a counterparty's default transaction category

Declare what spend at ONE counterparty is — asked once about the counterparty, instead of once per transaction. REQUIRED: company_id, from well_list_counterparties. category — a LABEL from the closed list this schema carries. The vocabulary is fixed: there is no free-text category and no way to mint one. **This is the counterparty's DEFAULT, not one row's category.** Every transaction of this counterparty categorized from here on takes the label without a model call. **It also reaches backward.** The counterparty's existing transactions are relabelled too, in the background over the minutes or hours after the call. Rows a person answered are never touched: a transaction someone categorized or confirmed by hand keeps what they gave it. Tell the user a declaration rewrites the counterparty's history, so they are not surprised by it. To change ONE row instead, use well_set_transaction_category, which sets that transaction and leaves the counterparty alone. **A declaration is trusted at once.** The other way a counterparty gets a default is by being taught: three corrections to the same category on three distinct transactions. A declaration skips that, because the person has already said what the answer is. **It overrides whatever the counterparty carried before**, including a category the system had inferred from corrections and one an earlier declaration already wrote onto these same rows. A later transaction-level correction still wins over the declaration on the row it names, and teaches the counterparty that the default is wrong. **Do not declare a default for a counterparty whose spend has more than one nature.** A marketplace or a cloud vendor selling hardware, compute and advertising to the same buyer has no single answer, and a declaration would state one. Leave those to the classifier and correct them per line. **Not for the workspace's own company.** A default is about the other party; the server refuses it on the own company. When the token authorizes one workspace, call this directly — no other tool call is needed first. When it authorizes several, this read will not guess which one you mean: pass `workspace_id` on the call.

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['company_id', 'category'], 'properties': {'category': {'enum': ['Subscription & product revenue', 'Services & implementation revenue', 'Grants & subsidies (non-repayable)', 'Research tax credit (CIR/CICE)', 'Other operating income & cashback', 'Employee salaries (net)', 'Employer social charges', 'Wage withholding remittance (PAS)', 'Employee benefits & insurance', 'Recruiting & hiring fees', 'Engineering / product contractors', 'Operations / GTM / other contractors', 'Legal & corporate-secretarial fees', 'Accounting, finance & advisory fees', 'Other professional & consulting fees', 'AI model / inference (cost of revenue)', 'Hosting, infrastructure & data (cost of revenue)', 'Developer & engineering software', 'Business & productivity software', 'Hardware & equipment', 'Advertising & paid media', 'Sales / marketing tools & lead-gen', 'AI creative & content production', 'Office rent & coworking', 'Office supplies & general operations', 'Travel & transport', 'Meals & entertainment', 'Team events & offsites', 'Bank, FX & payment-processing fees', 'Business insurance', 'Corporate income tax', 'Local & business taxes', 'Other operating expense (residual)', 'VAT receivable (input / refund)', 'VAT payable (output)', 'Treasury placement (out)', 'Treasury redemption (in)', 'Investment & interest income', 'Equity proceeds & raise costs', 'Loan drawdowns & repayments', 'Repayable public advances', 'Realised FX gain / loss', 'Inter-account transfer (same entity)', 'Inter-company transfer (own entities)', 'FX conversion principal', 'Uncategorised / suspense'], 'type': 'string', 'description': 'The category label spend at this counterparty defaults to. Must be one of the labels in this list.'}, 'company_id': {'type': 'string', '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)$', 'description': 'The counterparty to declare a default for, from well_list_counterparties.'}, 'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.'}, 'conversation_id': {'type': 'string', '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.'}, 'idempotency_key': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'error': {'type': 'string'}, 'success': {'type': 'boolean'}, 'category': {'type': 'string', 'description': "The label the counterparty's default now carries."}, 'company_id': {'type': 'string'}, 'company_name': {'type': 'string'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_set_own_company

Set own company

Set which company the workspace itself IS — the confirmed own-company anchor. REQUIRED: company_id — a company that ALREADY EXISTS in this workspace. Obtain it with well_query_records (companies) or well_create_company; this tool never creates one. This is a deliberate, accounting-critical write, not a convenience. Anchoring the own company overwrites the workspace's legal identity on its accounting settings (including clearing fields when the anchor moves), records a manual-confirm audit row, and syncs the billing customer name. It never re-posts existing journal entries. Confirm the exact company with the user before calling; never guess one from a name. Only a workspace owner or admin may set the own company. A caller without that role is refused, not silently ignored. well_start_close hard-gates on this anchor: a workspace with no own company cannot start a close.

Destructive

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['company_id'], 'properties': {'company_id': {'type': 'string', '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)$', 'description': 'The UUID of a company already in this workspace to anchor as its own company.'}, 'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.'}, 'conversation_id': {'type': 'string', '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.'}, 'idempotency_key': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'error': {'type': 'string'}, 'success': {'type': 'boolean'}, 'own_company_id': {'type': 'string', '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)$'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_set_transaction_category

Set a transaction's category

Set ONE transaction's category — the write that clears a categorization gate. REQUIRED: transaction_id, from well_list_uncategorized_window. category — the LABEL, exactly as that read returned it on the row's suggestion, or another label from the closed list this schema carries. The vocabulary is fixed: there is no free-text category and no way to mint one. **`decision` records HOW the category was chosen, and it changes what the row keeps.** - `accepted_classifier_suggestion` — the user affirmed the label the classifier had already put on the row. The row keeps `category_source: "classifier"` and its confidence score, and the affirmation is stamped as `category_confirmed_at`. Send this ONLY when the label equals the classifier's own stored suggestion. - `user_choice` — the user picked the label themselves. The row records `category_source: "user"` with no score. The server verifies an `accepted_classifier_suggestion` claim against the row it is writing and downgrades it to `user_choice` when the stored suggestion is not that label, so the claim can never manufacture classifier provenance. Omitting `decision` is a `user_choice`. **A row from `well_list_uncategorized_window` never qualifies for the affirmation.** That read returns rows carrying NO category at all, so there is no stored classifier value to affirm and the claim would be downgraded every time. Its `categorySuggestions` are PENDING proposals, not a stored category. Clearing that gate is always a `user_choice`; the affirmation exists for a surface that lists rows the classifier already categorized. Categorizing a row does NOT move it in or out of the internal-transfer rule — that rule counts payment-means legs and no label affects it. What a category DOES change is exemption matching: an uncategorized row can never be matched by an exemption and always stays in a sum. One transaction per call. The rows are decided independently and each one is saved as the user decides it. When the token authorizes one workspace, call this directly — no other tool call is needed first. When it authorizes several, this read will not guess which one you mean: pass `workspace_id` on the call.

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['transaction_id', 'category'], 'properties': {'category': {'enum': ['Subscription & product revenue', 'Services & implementation revenue', 'Grants & subsidies (non-repayable)', 'Research tax credit (CIR/CICE)', 'Other operating income & cashback', 'Employee salaries (net)', 'Employer social charges', 'Wage withholding remittance (PAS)', 'Employee benefits & insurance', 'Recruiting & hiring fees', 'Engineering / product contractors', 'Operations / GTM / other contractors', 'Legal & corporate-secretarial fees', 'Accounting, finance & advisory fees', 'Other professional & consulting fees', 'AI model / inference (cost of revenue)', 'Hosting, infrastructure & data (cost of revenue)', 'Developer & engineering software', 'Business & productivity software', 'Hardware & equipment', 'Advertising & paid media', 'Sales / marketing tools & lead-gen', 'AI creative & content production', 'Office rent & coworking', 'Office supplies & general operations', 'Travel & transport', 'Meals & entertainment', 'Team events & offsites', 'Bank, FX & payment-processing fees', 'Business insurance', 'Corporate income tax', 'Local & business taxes', 'Other operating expense (residual)', 'VAT receivable (input / refund)', 'VAT payable (output)', 'Treasury placement (out)', 'Treasury redemption (in)', 'Investment & interest income', 'Equity proceeds & raise costs', 'Loan drawdowns & repayments', 'Repayable public advances', 'Realised FX gain / loss', 'Inter-account transfer (same entity)', 'Inter-company transfer (own entities)', 'FX conversion principal', 'Uncategorised / suspense'], 'type': 'string', 'description': 'The category label to store. Must be one of the labels in this list.'}, 'decision': {'enum': ['accepted_classifier_suggestion', 'user_choice'], 'type': 'string', 'description': 'How the user arrived at the label. Omit for a user choice. See the description before sending accepted_classifier_suggestion.'}, 'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.'}, 'transaction_id': {'type': 'string', '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)$', 'description': 'The transaction to categorize, from well_list_uncategorized_window.'}, 'conversation_id': {'type': 'string', '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.'}, 'idempotency_key': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'error': {'type': 'string'}, 'success': {'type': 'boolean'}, 'category': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': 'The label stored on the row after the write.'}, 'transaction_id': {'type': 'string'}, 'category_source': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': 'Provenance the server settled on: "classifier" when it accepted the affirmation claim, "user" when the caller picked the label or the claim was downgraded.'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'category_confidence': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "The classifier's score, preserved only on an accepted affirmation. Null on a user choice."}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_set_transaction_ledger_account

Set a transaction's ledger account

Attach ONE transaction to the ledger account its journal entry should post to — the write that clears a posting gap. REQUIRED: transaction_id, from `well_list_unposted_transactions`. ledger_account_id — an account id from that read's `ledgerCatalog`, or from the row's own `ledger_suggestions`. Pass `null` to DETACH the account rather than to leave it unchanged; omitting the field is not how you clear one, because the field is required here. **Attaching the account does not, on its own, clear the gate.** The worklist selects on posting attempts, not on whether an account is present, so a row you attach and leave will come back on the next read. Posting is what clears it. Set `no_invoice_expected: true` to post the entry in the same call. Send it ONLY for a row whose `expects_supplier_invoice` is false on `well_list_unposted_transactions`, which is the read that carries that field: it asserts that no supplier invoice is coming, which is what makes the transaction bookable on its own. A row still waiting for its invoice must be attached WITHOUT it — the invoice is its blocker, and posting early books an entry the invoice would then contradict. Omit the field and nothing posts: the account is recorded and the row stays on the worklist. Most categories already imply their account — the chart maps each category key to a canonical code — so reach for this for the rows the category alone cannot settle, and for a deliberate override. When the token authorizes one workspace, call this directly — no other tool call is needed first. When it authorizes several, this read will not guess which one you mean: pass `workspace_id` on the call.

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['transaction_id', 'ledger_account_id'], 'properties': {'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.'}, 'transaction_id': {'type': 'string', '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)$', 'description': 'The transaction to attach, from well_list_unposted_transactions.'}, 'conversation_id': {'type': 'string', '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.'}, 'idempotency_key': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.'}, 'ledger_account_id': {'anyOf': [{'type': 'string', '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': 'null'}], 'description': 'The ledger account to attach. `null` DETACHES the account currently on the row.'}, 'no_invoice_expected': {'type': 'boolean', 'const': True, 'description': 'Assert no supplier invoice is coming, and post the entry to the attached account in the same call. Only for a row whose `expects_supplier_invoice` is false.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'error': {'type': 'string'}, 'posted': {'type': 'boolean'}, 'success': {'type': 'boolean'}, 'transaction_id': {'type': 'string'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'posting_outcome': {'type': 'string'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_show_accounting_settings

Show accounting settings

Draw the accounting-setup card so the USER reviews and confirms the workspace's accounting settings: country of incorporation, incorporation date, tax ID, fiscal year start, base currency, and accounting framework. This is the tool for every step that asks the user to complete, review, or CONFIRM the accounting settings — the close-books settings step, an onboarding "set up your books" step. It DRAWS the card, shows each row's provenance and the stored "Suggested" fills, lets the user edit what is wrong, and waits for their Confirm. Reach for it directly on such a step; do NOT read the settings first with the silent tool and then decide to draw — drawing the card IS the step. The card gates its Confirm on the required set (fiscal year start and base currency by default; widen it with `required` when a step needs more). ONLY when a step needs the values WITHOUT the user seeing a card (a silent gate check) call `well_get_accounting_settings` instead.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'title': {'type': 'string', 'maxLength': 120, 'description': 'Heading for the accounting-setup card, OVERRIDING the default wording. Use it to frame the step in its flow (e.g. "Confirm your accounting settings for the close"). At most 120 characters. Omit for the default wording.'}, 'required': {'type': 'array', 'items': {'enum': ['country', 'incorporation_date', 'tax_id', 'fiscal_year_start_month', 'base_currency', 'accounting_framework'], 'type': 'string'}, 'minItems': 1, 'description': 'The card fields the user MUST fill before Confirm is enabled, as an exact list from ["country","incorporation_date","tax_id","fiscal_year_start_month","base_currency","accounting_framework"]. Omit to gate on the default set ["fiscal_year_start_month","base_currency"]; widen it when a step needs more (never narrow below the default).'}, 'subtitle': {'type': 'string', 'maxLength': 240, 'description': "Supporting line under the card's heading. At most 240 characters. Omit for the default."}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which."}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'error': {'type': 'string'}, 'success': {'type': 'boolean'}, 'required': {'type': 'array', 'items': {'enum': ['country', 'incorporation_date', 'tax_id', 'fiscal_year_start_month', 'base_currency', 'accounting_framework'], 'type': 'string'}}, 'settings': {'type': 'object', 'required': ['country', 'base_currency', 'accounting_framework', 'fiscal_year_start_month', 'fiscal_year_start_month_source', 'fiscal_year_start_locked', 'first_fiscal_year_start_date', 'first_fiscal_year_start_source', 'coa_confirmed', 'coa_confirmed_source', 'field_provenance', 'incorporation_date', 'registered_name', 'trade_name', 'registered_value', 'domain', 'business_type', 'address', 'own_company_id', 'created_at', 'updated_at', 'tax_id'], 'properties': {'domain': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'tax_id': {'type': 'object', 'required': ['present', 'source', 'suggestion_available'], 'properties': {'source': {'anyOf': [{'enum': ['ai', 'registry', 'derived', 'user'], 'type': 'string'}, {'type': 'null'}]}, 'present': {'type': 'boolean'}, 'suggestion_available': {'type': 'boolean'}}, 'additionalProperties': False}, 'address': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'country': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'created_at': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'trade_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'updated_at': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'base_currency': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'business_type': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'coa_confirmed': {'anyOf': [{'type': 'boolean'}, {'type': 'null'}]}, 'own_company_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'registered_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'field_provenance': {'anyOf': [{'type': 'object', 'properties': {'tax_id': {'type': 'object', 'required': ['source', 'confidence', 'reason', 'recorded_at'], 'properties': {'reason': {'anyOf': [{'enum': ['registry_match', 'email_domain', 'country_default', 'invoice_header', 'agent_setup'], 'type': 'string'}, {'type': 'null'}]}, 'source': {'enum': ['ai', 'registry', 'derived', 'user'], 'type': 'string'}, 'confidence': {'anyOf': [{'type': 'number', 'maximum': 1, 'minimum': 0}, {'type': 'null'}]}, 'recorded_at': {'type': 'string'}}, 'additionalProperties': False}, 'country': {'type': 'object', 'required': ['source', 'confidence', 'reason', 'recorded_at'], 'properties': {'reason': {'anyOf': [{'enum': ['registry_match', 'email_domain', 'country_default', 'invoice_header', 'agent_setup'], 'type': 'string'}, {'type': 'null'}]}, 'source': {'enum': ['ai', 'registry', 'derived', 'user'], 'type': 'string'}, 'confidence': {'anyOf': [{'type': 'number', 'maximum': 1, 'minimum': 0}, {'type': 'null'}]}, 'recorded_at': {'type': 'string'}}, 'additionalProperties': False}, 'base_currency': {'type': 'object', 'required': ['source', 'confidence', 'reason', 'recorded_at'], 'properties': {'reason': {'anyOf': [{'enum': ['registry_match', 'email_domain', 'country_default', 'invoice_header', 'agent_setup'], 'type': 'string'}, {'type': 'null'}]}, 'source': {'enum': ['ai', 'registry', 'derived', 'user'], 'type': 'string'}, 'confidence': {'anyOf': [{'type': 'number', 'maximum': 1, 'minimum': 0}, {'type': 'null'}]}, 'recorded_at': {'type': 'string'}}, 'additionalProperties': False}, 'incorporation_date': {'type': 'object', 'required': ['source', 'confidence', 'reason', 'recorded_at'], 'properties': {'reason': {'anyOf': [{'enum': ['registry_match', 'email_domain', 'country_default', 'invoice_header', 'agent_setup'], 'type': 'string'}, {'type': 'null'}]}, 'source': {'enum': ['ai', 'registry', 'derived', 'user'], 'type': 'string'}, 'confidence': {'anyOf': [{'type': 'number', 'maximum': 1, 'minimum': 0}, {'type': 'null'}]}, 'recorded_at': {'type': 'string'}}, 'additionalProperties': False}, 'accounting_framework': {'type': 'object', 'required': ['source', 'confidence', 'reason', 'recorded_at'], 'properties': {'reason': {'anyOf': [{'enum': ['registry_match', 'email_domain', 'country_default', 'invoice_header', 'agent_setup'], 'type': 'string'}, {'type': 'null'}]}, 'source': {'enum': ['ai', 'registry', 'derived', 'user'], 'type': 'string'}, 'confidence': {'anyOf': [{'type': 'number', 'maximum': 1, 'minimum': 0}, {'type': 'null'}]}, 'recorded_at': {'type': 'string'}}, 'additionalProperties': False}, 'fiscal_year_start_month': {'type': 'object', 'required': ['source', 'confidence', 'reason', 'recorded_at'], 'properties': {'reason': {'anyOf': [{'enum': ['registry_match', 'email_domain', 'country_default', 'invoice_header', 'agent_setup'], 'type': 'string'}, {'type': 'null'}]}, 'source': {'enum': ['ai', 'registry', 'derived', 'user'], 'type': 'string'}, 'confidence': {'anyOf': [{'type': 'number', 'maximum': 1, 'minimum': 0}, {'type': 'null'}]}, 'recorded_at': {'type': 'string'}}, 'additionalProperties': False}}, 'additionalProperties': False}, {'type': 'null'}]}, 'registered_value': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'incorporation_date': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'accounting_framework': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'coa_confirmed_source': {'anyOf': [{'type': 'string', 'const': 'user'}, {'type': 'null'}]}, 'fiscal_year_start_month': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'fiscal_year_start_locked': {'type': 'boolean'}, 'first_fiscal_year_start_date': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'first_fiscal_year_start_source': {'anyOf': [{'enum': ['derived', 'user'], 'type': 'string'}, {'type': 'null'}]}, 'fiscal_year_start_month_source': {'anyOf': [{'enum': ['derived', 'registry', 'user'], 'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}, 'next_step': {'type': 'string', 'description': 'What to do with the card this result renders. Added by the dispatcher when the card asks for a click.'}, 'suggestions': {'type': 'object', 'properties': {'tax_id': {'type': 'array', 'items': {'type': 'object', 'required': ['value', 'label', 'source', 'reason', 'confidence', 'country'], 'properties': {'label': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'value': {'type': 'string'}, 'reason': {'anyOf': [{'enum': ['registry_match', 'email_domain', 'country_default', 'invoice_header', 'agent_setup'], 'type': 'string'}, {'type': 'null'}]}, 'source': {'enum': ['ai', 'registry', 'derived', 'user'], 'type': 'string'}, 'country': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'confidence': {'anyOf': [{'type': 'number', 'maximum': 1, 'minimum': 0}, {'type': 'null'}]}, 'tax_id_type': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}}, 'country': {'type': 'array', 'items': {'type': 'object', 'required': ['value', 'label', 'source', 'reason', 'confidence', 'country'], 'properties': {'label': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'value': {'type': 'string'}, 'reason': {'anyOf': [{'enum': ['registry_match', 'email_domain', 'country_default', 'invoice_header', 'agent_setup'], 'type': 'string'}, {'type': 'null'}]}, 'source': {'enum': ['ai', 'registry', 'derived', 'user'], 'type': 'string'}, 'country': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'confidence': {'anyOf': [{'type': 'number', 'maximum': 1, 'minimum': 0}, {'type': 'null'}]}, 'tax_id_type': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}}, 'base_currency': {'type': 'array', 'items': {'type': 'object', 'required': ['value', 'label', 'source', 'reason', 'confidence', 'country'], 'properties': {'label': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'value': {'type': 'string'}, 'reason': {'anyOf': [{'enum': ['registry_match', 'email_domain', 'country_default', 'invoice_header', 'agent_setup'], 'type': 'string'}, {'type': 'null'}]}, 'source': {'enum': ['ai', 'registry', 'derived', 'user'], 'type': 'string'}, 'country': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'confidence': {'anyOf': [{'type': 'number', 'maximum': 1, 'minimum': 0}, {'type': 'null'}]}, 'tax_id_type': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}}, 'incorporation_date': {'type': 'array', 'items': {'type': 'object', 'required': ['value', 'label', 'source', 'reason', 'confidence', 'country'], 'properties': {'label': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'value': {'type': 'string'}, 'reason': {'anyOf': [{'enum': ['registry_match', 'email_domain', 'country_default', 'invoice_header', 'agent_setup'], 'type': 'string'}, {'type': 'null'}]}, 'source': {'enum': ['ai', 'registry', 'derived', 'user'], 'type': 'string'}, 'country': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'confidence': {'anyOf': [{'type': 'number', 'maximum': 1, 'minimum': 0}, {'type': 'null'}]}, 'tax_id_type': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}}, 'accounting_framework': {'type': 'array', 'items': {'type': 'object', 'required': ['value', 'label', 'source', 'reason', 'confidence', 'country'], 'properties': {'label': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'value': {'type': 'string'}, 'reason': {'anyOf': [{'enum': ['registry_match', 'email_domain', 'country_default', 'invoice_header', 'agent_setup'], 'type': 'string'}, {'type': 'null'}]}, 'source': {'enum': ['ai', 'registry', 'derived', 'user'], 'type': 'string'}, 'country': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'confidence': {'anyOf': [{'type': 'number', 'maximum': 1, 'minimum': 0}, {'type': 'null'}]}, 'tax_id_type': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}}, 'fiscal_year_start_month': {'type': 'array', 'items': {'type': 'object', 'required': ['value', 'label', 'source', 'reason', 'confidence', 'country'], 'properties': {'label': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'value': {'type': 'string'}, 'reason': {'anyOf': [{'enum': ['registry_match', 'email_domain', 'country_default', 'invoice_header', 'agent_setup'], 'type': 'string'}, {'type': 'null'}]}, 'source': {'enum': ['ai', 'registry', 'derived', 'user'], 'type': 'string'}, 'country': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'confidence': {'anyOf': [{'type': 'number', 'maximum': 1, 'minimum': 0}, {'type': 'null'}]}, 'tax_id_type': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}}}, 'additionalProperties': False}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_show_company_candidates

Show the company candidates

Show the user the detected COMPANY candidates on a card and let them pick which company is theirs: a tile per detected company candidate with its confidence, and a company-registry search at the top for the case where none was detected. ⚠️ ONLY for the zero-company case — a membership workspace with no own company attached — when the user must choose or find the company to create the workspace from. For the values alone, read `well_get_own_company`, which draws nothing. ⚠️ WAIT ON THE CARD IN THE TURN THAT DREW IT. Write your one line for the user FIRST — the wait holds the turn open for up to a minute, and a user looking at a card with no sentence beside it has been given no reason to click — then call `well_wait_for_selection({ kind: "company_pick" })`, which this result's `next_step` also states. The card's own footer mints the company workspace and switches into it on the click, so never mint it yourself after the pick. ⚠️ NEVER PICK THE COMPANY for the user, and never infer it from the workspace name.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which."}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['anchor', 'candidates', 'success'], 'properties': {'error': {'type': 'string'}, 'anchor': {'anyOf': [{'type': 'object', 'required': ['company_id', 'registered_name', 'trade_name'], 'properties': {'company_id': {'type': 'string'}, 'trade_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'registered_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}, {'type': 'null'}]}, 'success': {'type': 'boolean'}, 'next_step': {'type': 'string', 'description': 'What to do with the card this result renders. Added by the dispatcher when the card asks for a click.'}, 'candidates': {'type': 'array', 'items': {'type': 'object', 'required': ['candidate_id', 'company_id', 'registered_name', 'trade_name', 'role', 'state', 'confidence_score', 'domain', 'remote_logo_url', 'country', 'business_type', 'confirmable', 'confirmable_reason'], 'properties': {'role': {'anyOf': [{'enum': ['primary', 'sibling'], 'type': 'string'}, {'type': 'null'}]}, 'state': {'enum': ['pending', 'confirmed', 'dismissed', 'snoozed'], 'type': 'string'}, 'domain': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "The company's domain, a logo source and a display fallback."}, 'country': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "The company's country, for a light detail panel."}, 'company_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'trade_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'confirmable': {'type': 'boolean', 'description': 'Whether well_create_company_workspace accepts this candidate now. False for a name-only detected candidate with no groundable identity, or one that has left the surfaced set.'}, 'candidate_id': {'type': 'string', 'description': "The candidate's id — pass to well_create_company_workspace to mint the company workspace from it."}, 'business_type': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "The company's legal form (SAS, Inc, GmbH), when known."}, 'registered_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'remote_logo_url': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': 'A resolved logo url when one is known; null otherwise.'}, 'confidence_score': {'type': 'number'}, 'confirmable_reason': {'anyOf': [{'enum': ['not_open', 'not_surfaceable', 'not_primary', 'already_confirmed', 'not_grounded'], 'type': 'string'}, {'type': 'null'}], 'description': 'Why confirmable is false, null when true. not_grounded: no registry or tax identifier to mint from; ask the user to search the registry and pick the verified entry. not_open: no longer the surfaced candidate; re-read the own-company list before acting. Others: not_primary, already_confirmed, not_surfaceable.'}}, 'additionalProperties': False}}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_show_records

Show records

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 }.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['root'], 'properties': {'root': {'type': 'string', 'description': '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.'}, 'limit': {'type': 'number', 'maximum': 500, 'minimum': 1, 'description': 'Max records to return (default 50, max 500)'}, 'cursor': {'type': 'string', 'description': 'Opaque cursor for the next page. Omit for the first page, then pass nextCursor from the previous response.'}, 'fields': {'type': 'array', 'items': {'type': 'array', 'items': {'type': 'string'}}, 'description': "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."}, 'orderBy': {'type': 'object', 'required': ['field', 'direction'], 'properties': {'field': {'type': 'string', 'description': 'Field name to sort by'}, 'direction': {'enum': ['asc', 'desc'], 'type': 'string', 'description': 'Sort direction'}}, 'description': 'Sort results by a field. Example: { field: "grand_total", direction: "desc" }'}, 'allFields': {'type': 'boolean', 'description': 'If true, automatically fetches all scalar fields from schema. No need to specify fields.'}, 'partyScope': {'enum': ['purchase', 'sales', 'intra_self', 'unattributed'], 'type': 'string', '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.'}, 'whereClause': {'type': 'object', 'description': 'Hasura-style filter object. Operators: _eq, _neq, _gt, _gte, _lt, _lte, _like, _ilike, _in, _nin, _is_null. Example: { "status": { "_eq": "unpaid" } }', 'propertyNames': {'type': 'string'}, 'additionalProperties': {}}, 'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit to query every authorized workspace at once; each row comes back tagged with the workspace it belongs to.'}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['rows', 'totalCount', 'returned', 'success'], 'properties': {'rows': {'type': 'array', 'items': {'type': 'object', 'propertyNames': {'type': 'string'}, 'additionalProperties': {}}, 'description': 'Query results'}, 'error': {'type': 'string'}, 'columns': {'type': 'array', 'items': {'type': 'string'}, '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."}, 'success': {'type': 'boolean'}, 'returned': {'type': 'number', 'description': 'Number of rows returned'}, 'columnMeta': {'type': 'object', 'description': '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.', 'propertyNames': {'type': 'string'}, 'additionalProperties': {'type': 'object', 'properties': {'context': {'type': 'string'}, 'enrichment': {'type': 'string'}}, 'additionalProperties': False}}, 'nextCursor': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': 'Cursor for the next page. null means last page.'}, 'totalCount': {'type': 'number', 'description': 'Total matching records'}, 'records_url': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "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': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_show_retargetable_connectors

Show retargetable connectors

Draw the connector-retarget card so the USER brings a bank (or other ledger) connector across from the membership workspace to this company workspace. A connector connected on the parent (membership) workspace syncs its transactions there, where they cannot post. This card lists each such connector that could follow this workspace, with how strongly it was proved to belong here and how much history is behind it, pre-ticks the strong matches, and on Confirm retargets the ones the user keeps: a new connector row is created here that borrows the parent's credentials and pulls the history in on its own first sync. Draw it on the close-books bank step to SHOW the user the connectors they can bring across, let them pick which, and CONFIRM the bring-across, once at least one candidate carries a proof tier other than "no_match" and a transaction count above zero. Drawing the card IS that step, and it waits for the user's Confirm. ONLY when a step needs the candidate count WITHOUT the user seeing a card (a silent gate check that decides whether to offer the card at all) call `well_list_retargetable_connectors` instead.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'title': {'type': 'string', 'maxLength': 120, 'description': 'Heading for the connector-retarget card, OVERRIDING the default wording. Use it to frame the step in its flow (e.g. "Bring your bank across for the close"). At most 120 characters. Omit for the default wording.'}, 'subtitle': {'type': 'string', 'maxLength': 240, 'description': "Supporting line under the card's heading. At most 240 characters. Omit for the default."}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which."}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'error': {'type': 'string'}, 'success': {'type': 'boolean'}, 'next_step': {'type': 'string', 'description': 'What to do with the card this result renders. Added by the dispatcher when the card asks for a click.'}, 'candidates': {'type': 'array', 'items': {'type': 'object', 'required': ['workspace_connector_id', 'service_id', 'name', 'proof_tier', 'transaction_count', 'earliest_transaction_date', 'latest_transaction_date', 'source_workspace', 'preselected'], 'properties': {'name': {'type': 'string'}, 'proof_tier': {'enum': ['canonical_id', 'name_country', 'no_match'], 'type': 'string'}, 'service_id': {'type': 'string'}, 'preselected': {'type': 'boolean'}, 'source_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'type': 'string'}, 'workspace_id': {'type': 'string', '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)$'}}, 'additionalProperties': False}, 'transaction_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'workspace_connector_id': {'type': 'string', '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)$'}, 'latest_transaction_date': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'earliest_transaction_date': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_show_workspace_picker

Show the workspace picker

Ask the user WHICH workspace to work in, on a card: one tile per authorized workspace, with its logo and the company behind it. ⚠️ ONLY when the token authorizes SEVERAL workspaces and no hint resolves to one. Every other case is yours to settle with `well_list_workspaces`, which draws nothing: exactly one workspace in the grant, a name or company the user already named, a pin this conversation itself wrote, or no workspace at all. A chooser over a set of one asks nothing, and a chooser you could have answered yourself asks the reader a question you already know the answer to. ⚠️ WAIT ON THE CARD IN THE TURN THAT DREW IT. Write your one line for the user FIRST — the wait holds the turn open for up to a minute, and a user looking at a card with no sentence beside it has been given no reason to click — then call `well_wait_for_selection({ kind: "workspace" })`, which this result's `next_step` also states. The click writes the pin server-side, so never follow it with `well_switch_workspace`. ⚠️ NEVER DEFAULT TO THE PRIMARY WORKSPACE on the user's behalf, and do not restate the workspaces in text under the card. ⚠️ WRITE `reply` IN THE USER'S LANGUAGE, WITH `{picked}` WHERE THE WORKSPACE NAME BELONGS. A click sends that sentence into the conversation as the person's own message, and the card puts the workspace they actually picked in place of the placeholder. A sentence left unwritten sends English to a reader who is not writing in English; a sentence that names a workspace itself is refused, because you are writing it before they have chosen. The rows are the rows of `well_list_workspaces`, field for field. Its description carries the field reference, and this description does not repeat it.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'reply': {'type': 'string', 'maxLength': 160, 'minLength': 1, 'description': 'One sentence, IN THE LANGUAGE THE USER IS WRITING IN, that the click sends into the conversation as their own message. Write what the PERSON would say about the workspace they pick, in their words, not an instruction to yourself. You write it BEFORE they click, so you cannot know what they will choose: put {picked} where the pick belongs and the card replaces it with the names they actually picked, one or several. In English it would read "Let\'s work on {picked}." Write the same shape in the user\'s language. {picked} is required: a sentence that names a pick itself names the one you guessed, so the card refuses it and sends its own English instead. At most 160 characters. Omitted sends an English sentence the card builds itself, which is wrong for any reader not writing in English.'}, 'title': {'type': 'string', 'maxLength': 120, 'minLength': 1, 'description': 'Heading for the picker card, framing the step in its flow (e.g. "Which company are we closing?"). At most 120 characters. Omit to keep the default wording; an empty string is rejected rather than rendered as a blank heading.'}, 'subtitle': {'type': 'string', 'maxLength': 240, 'minLength': 1, 'description': "Supporting line under the picker card's heading. At most 240 characters. Omit to keep the default wording; an empty string is rejected rather than rendered blank."}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Optional: this tool describes the token itself rather than one workspace's data, so omitting it returns the same answer."}, 'workspace_ids': {'type': 'array', 'items': {'type': 'string'}, 'minItems': 1, 'description': 'Scope the tiles to this subset of the authorized workspaces, e.g. the company workspaces under one membership. Every id must be one this token authorizes; an id outside the grant refuses the call. Omit to draw every authorized workspace.'}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['workspaces', 'success'], 'properties': {'error': {'type': 'string'}, 'session': {'type': 'object', 'required': ['pinned_workspace_id', 'workspace_queue', 'selected_periods', 'selected_counterparties'], 'properties': {'workspace_queue': {'type': 'array', 'items': {'type': 'string'}}, 'selected_periods': {'type': 'array', 'items': {'type': 'object', 'required': ['calendar_year', 'calendar_month'], 'properties': {'calendar_year': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'calendar_month': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}}, 'additionalProperties': False}}, 'pinned_workspace_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'selected_counterparties': {'anyOf': [{'type': 'object', 'required': ['workspace_id', 'counterparties'], 'properties': {'workspace_id': {'type': 'string', 'description': 'The workspace the picked company ids belong to.'}, 'counterparties': {'type': 'array', 'items': {'type': 'object', 'required': ['company_id', 'matched_connector_service_id'], 'properties': {'company_id': {'type': 'string'}, 'matched_connector_service_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "The connector that can fetch this counterparty's invoices; null when none matched."}}, 'additionalProperties': False}}}, 'additionalProperties': False}, {'type': 'null'}], 'description': 'The counterparties picked on the missing-invoices card; null until a pick is recorded.'}}, 'description': "What this conversation's card clicks recorded so far; null/empty fields when nothing was clicked yet.", 'additionalProperties': False}, 'success': {'type': 'boolean'}, 'next_step': {'type': 'string', 'description': 'What to do with the card this result renders. Added by the dispatcher when the card asks for a click.'}, 'workspaces': {'type': 'array', 'items': {'type': 'object', 'required': ['workspace_id', 'workspace_name', 'is_primary', 'own_company_id', 'lineage_parent_workspace_id', 'has_bank_transactions', 'identity'], 'properties': {'identity': {'type': 'object', 'required': ['registered_name', 'trade_name', 'registered_value', 'country', 'domain', 'base_currency', 'fiscal_year_start_month', 'fiscal_year_start_month_source', 'country_default_fiscal_year_start_month'], 'properties': {'domain': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'country': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'trade_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'base_currency': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'registered_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'registered_value': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'fiscal_year_start_month': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'fiscal_year_start_month_source': {'anyOf': [{'enum': ['derived', 'registry', 'user'], 'type': 'string'}, {'type': 'null'}], 'description': 'Where fiscal_year_start_month came from: "registry" from a company registry, "derived" from the country fallback, "user" from a human. Null when never set. Tells a confirmed fiscal year from one resting on a default.'}, 'country_default_fiscal_year_start_month': {'anyOf': [{'type': 'number'}, {'type': 'null'}], 'description': "The jurisdiction's default fiscal-year-start month for this country, or null when the country has no single confident default (non-null for France only today)."}}, 'additionalProperties': False}, 'is_primary': {'type': 'boolean'}, 'workspace_id': {'type': 'string'}, 'own_company_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': 'The public id of the company this workspace is anchored to, or null. A row that carries it is a company workspace, the one the close flow runs in; a row without it is a membership workspace.'}, 'workspace_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'has_bank_transactions': {'anyOf': [{'type': 'boolean'}, {'type': 'null'}], 'description': 'Whether a connector the workspace BANKS with has delivered any transaction to it: a bank, a neobank, or a treasury or spend platform whose product is an account. An accounting platform and a payment processor deliver transactions too and do NOT count. A transaction whose source connector is unknown, whose install has since been disconnected, or whose catalog entry has been retired does not count either. Only true shows a bank has fed this workspace. false means no such transaction was found; null means the signal could not be read. An absent value is not a zero, and neither false nor null licenses skipping a bank-connection step.'}, 'lineage_parent_workspace_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': "The workspace_id of the membership this workspace was created under, or null when it has no active lineage. Its parent's own row is the membership whose id this points at."}}, 'additionalProperties': False}}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_sum_invoices

Sum invoices over a window

Sum a workspace's billed amounts over a window of whole months, grouped by month, currency and billing context. Arithmetic only — this tool holds no definition of MRR or recurrence, and returns no figure the app renders. Use it when you are computing a figure whose RULES you are stating yourself: recurring revenue over a window you chose, a total restricted to the billing contexts a reader confirmed, a per-month series behind a trend you are about to describe. The server derives no MRR of its own, so an MRR figure starts here: state the rules, sum exactly those rows, then put the result on a card with `well_render_mrr`. **The window is whole months.** `from` and `to` are both the first day of a month, as YYYY-MM-01; `from` is inclusive and `to` is EXCLUSIVE, so June to August is `2026-06-01` to `2026-09-01`. A bound inside a month is refused rather than widened, and so is a window longer than 36 months. **Which rows are billed amounts is decided here, and stated so you can say it.** A canceled invoice is left out. Only billing documents count: invoices, debit notes, credit notes and subscription billing statements, so a proforma and the invoice it precedes are not summed twice, and an order, a quote or a payment advice never is. A row with no document type is read as an invoice. Every amount is NET of tax (`items_total`), because tax collected is owed onward rather than earned. **`party_scope` is required, and it decides whose invoice this is.** `sales` is what the workspace ISSUED — its receivables, and the only side revenue can come from. `purchase` is what it received. The two are the same rows read from opposite ends, so no default is offered: a server choosing a side would answer a different question from the one asked. `intra_self` is an invoice between two companies the workspace owns, and `unattributed` is one Well could place on neither side. **Those four scopes partition every invoice exactly once**, which is what makes an incomplete picture visible rather than silent. `unattributed_count` comes back on every call, whatever scope you asked for: it counts the invoices in the window that landed in that fourth bucket. State it beside any total, because an unattributed invoice may still belong in the figure and nothing here can tell you whether it does. **Every row carries ONE month, ONE currency and ONE billing context.** Currency is always a grouping key, named or not: adding EUR to USD gives a number denominated in nothing, and no field on the result would tell you it happened. Convert the per-currency subtotals yourself, at a rate you can state, before you add them. **`sum` is already net of credit notes.** A credit note subtracts its magnitude from its own month-currency-context bucket, whichever sign it was stored with; `credit_note_sum` and `credit_note_count` report what that removed, so you can say what the figure netted. Do not subtract them a second time. A bucket whose credit notes outweigh its invoices nets negative, and that is a real state rather than an error. **`billing_context` is `null` on rows that name no billing arrangement** — none stored, `unknown`, or a value Well has no label for — and that is a third answer rather than a kind of one-off. The field is filled by extraction, not by a billing system, so a workspace can carry real recurring revenue on rows that say nothing about it. `unclassified_count` totals those rows. The recurring-contexts card offers them as one choice, keyed `"unclassified"`, so apply that key to these rows and only these. Counted or not, report the count rather than letting a reader read the remainder as "everything else". `corrected_or_consolidated_count` counts the corrected and consolidated invoices among the rows. Each replaces invoices Well holds no link to, so when those originals fall in the same window the sum counts that billing twice. The rows keep them, because dropping them would lose the revenue whenever the originals fall outside the window. State the count beside any total whenever it is not zero. `excluded_malformed` counts billing documents in the window with no readable net amount or no currency. They are in none of the rows and none of the sums, so state the count beside any total. It comes back `null` when the count could not be read, which is NOT `0`: zero says every row was readable, null says nobody counted. `partial: true` means the aggregate was cut short and every figure is a FLOOR rather than a measurement. When the token authorizes one workspace, call this directly — no other tool call is needed first. When it authorizes several, this read will not guess which one you mean: pass `workspace_id` on the call.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['from', 'to', 'party_scope'], 'properties': {'to': {'type': 'string', 'pattern': '^(\\d{4})-(\\d{2})-01$', 'description': 'EXCLUSIVE end of the window: the first day of the month after the last one you want, YYYY-MM-01.'}, 'from': {'type': 'string', 'pattern': '^(\\d{4})-(\\d{2})-01$', 'description': 'Inclusive start of the window: the first day of a month, YYYY-MM-01.'}, 'party_scope': {'enum': ['purchase', 'sales', 'intra_self', 'unattributed'], 'type': 'string', 'description': 'Which side of the invoice the workspace occupies: `sales` for what it issued, `purchase` for what it received. Required; see the description.'}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which."}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['rows', 'window', 'unattributed_count', 'unclassified_count', 'corrected_or_consolidated_count', 'excluded_malformed', 'partial', 'success'], 'properties': {'rows': {'type': 'array', 'items': {'type': 'object', 'required': ['month', 'currency', 'billing_context', 'sum', 'count', 'credit_note_sum', 'credit_note_count'], 'properties': {'sum': {'type': 'number'}, 'count': {'type': 'number'}, 'month': {'type': 'string'}, 'currency': {'type': 'string'}, 'billing_context': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'credit_note_sum': {'type': 'number'}, 'credit_note_count': {'type': 'number'}}, 'additionalProperties': False}}, 'error': {'type': 'string'}, 'window': {'type': 'object', 'required': ['from', 'to'], 'properties': {'to': {'type': 'string'}, 'from': {'type': 'string'}}, 'additionalProperties': False}, 'partial': {'type': 'boolean'}, 'success': {'type': 'boolean'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'excluded_malformed': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'unattributed_count': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'unclassified_count': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}, 'corrected_or_consolidated_count': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}}, 'additionalProperties': False}

well_sum_transactions

Sum transactions over a window

Sum a workspace's transactions over a date window, grouped how you ask. Arithmetic only — this tool holds no definition of burn, spend, or runway, and returns no figure the app renders. Use it when you are computing a figure whose RULES you are stating yourself: a burn over a window you chose, a total that excludes categories the user named, a per-month series behind a trend you are about to describe. The server derives no burn of its own, so a burn figure starts here: state the rules, sum exactly those rows, then put the result on a card with `well_render_burn`. `from` is inclusive and `to` is EXCLUSIVE, so a window of whole months passes the first instant of the month after the last one you want. Both are required: a window you cannot state is a decision you have not made, and this tool will not pick one for you. `axes` groups the result (any of `month`, `currency`, `category`, `ledger_account`, `category_label`, `transaction_type`, comma-separated) and names what to group in ADDITION to currency. Every axis appears on every row: the ones you did not group by come back `null`, so the row shape never depends on what you asked for. **On an axis you DID name, a `null` is a group, not a gap.** It is the rows whose column is empty, and it carries its own sums and counts like any other group. A group's rows are `count_negative + count_positive`, so the null group's share of that total is the part that axis cannot label. Both counts cover readable, non-zero rows only: a zero amount is in neither branch, and unreadable ones are in `excluded_malformed`. So the share is a share of the rows this tool could sum, not of every row in the window. What that share means, and which grouping is worth using, is yours to decide: this tool holds no view on it. What each labelling axis IS: - `ledger_account`: the name on the workspace's own chart of accounts. It may have been written by an accounting sync rather than chosen by a person, so do not call it the user's own categorization without checking the `ledger_accounts` root for the connector that wrote it. A blank label reads as `null`. A soft-deleted or inactive account still carries its name, because this axis reports what the row was labelled at the time, not what the current chart of accounts holds. It groups on the NAME, and a chart of accounts is unique on the account number rather than the name, so two accounts sharing one name arrive as a single group carrying both their sums. That is one slice per label, which is what a breakdown by label means, but it is not one slice per account: do not read a group here as an account. - `category`: the typed catalog key, and the ONLY value `exempt_categories` accepts. A key the catalog no longer carries is still populated here, so it groups under a key that names nothing a reader would recognise. - `category_label`: the stored display label, which a connector may have written in its own language. Never pass one to `exempt_categories`; it is not a key. - `transaction_type`: the transaction's own type. Each value is a full sentence rather than a code, and almost every row carries one. **At most 500 groups come back, biggest first.** Past that the smallest are dropped and `rows_truncated` is true, which is NOT `partial`: everything here was measured exactly and only the tail is missing. A total over a truncated result is a floor, and an axis's coverage cannot be read off one at all, because the null group may be among the dropped. Group on fewer axes, or over a shorter window, and ask again. **Currency is always grouped, named or not, so a row never mixes two.** Adding EUR to USD gives a number denominated in nothing, and no field on the result would tell you it happened. Omitting `axes` therefore returns one row PER CURRENCY over the window, not one row. Convert the per-currency subtotals yourself, at a rate you can state, before you add them — and if there is more than one row and you report a single total without converting, the total is wrong. **Each row carries BOTH sign branches, and choosing between them is your job.** `sum_negative` is the magnitude of the rows whose amount is negative; `sum_positive` is the magnitude of the rows whose amount is positive; `count_negative` and `count_positive` say how many rows are behind each. Which one is money leaving depends on the FEED, not on the query: most connectors store outflows as negatives, some store them as positive magnitudes. Read the counts to decide, and decide ONCE over the whole window rather than per row or per group: a single category or month can be all-positive on a signed feed, so electing per group flips the convention mid-answer and totals two different things together. A window whose rows are overwhelmingly negative is a signed feed, and outflow is `sum_negative`. Almost no negatives means the feed stores magnitudes and keeps direction in a field this tool does not group on — so it cannot separate outflow from inflow, and `sum_negative + sum_positive` is gross movement, not spend. Say so rather than reporting it as an outflow. **A substantial share of BOTH is a third answer, not a close call between the first two.** A workspace connected to a signed feed and a magnitude feed at once pools them here, and no combination of the two subtotals is its outflow: `sum_negative` misses the magnitude feed's spend entirely, and adding `sum_positive` pulls in the signed feed's income. There is no grouping that separates them, because the axes carry no connector. Report that the window mixes conventions and that a single outflow cannot be derived from it, rather than electing whichever branch is nearer. State which convention you elected and what the counts were, so the reader can check it. **`scope` is required, and it decides which rows are this workspace's.** `own_and_adopted` is the population the burn tile counts: the workspace's own transactions plus any a parent workspace shared with it through an adoption grant, with legs tested against the parent's accounts too. `own` is the workspace's own transactions only, tested against its own accounts — the rows its balances move with. Use `own` when the sum is reconciled against the workspace's own balances, as a cash-flow bridge is, and `own_and_adopted` for a burn. On most workspaces the two agree; on a child workspace they do not, which is why neither is a default. `exclude_internal_transfers: true` keeps only the rows with EXACTLY ONE leg on an account the workspace owns. Two legs is a movement between your own accounts and drops, which is the rule's purpose. **Zero legs also drops**, and that is the part worth knowing: a card purchase sits against a liability account, so on a card-heavy workspace this removes card spend along with the transfers. `excluded_zero_leg` and `excluded_multi_leg` count the two populations separately, so read them before describing what the figure covers. Read `excluded_zero_leg` as "this many rows carried no asset movement" and nothing narrower: a card charge lands there, and so does a row whose payer and payee resolved to no account at all. `excluded_no_owned_leg` is that second part on its own: rows with no leg on ANY owned account, liabilities included, so card spend is never in it. Those rows could not be attributed to an account and may have moved a balance the sums cannot see, so a figure reconciled against balances treats a non-zero count as flows that are incomplete. A large `excluded_zero_leg` is a reason to look, never a spend total to quote. Any of the three counts comes back as `null` when it could not be measured, which is NOT `0`: zero says the rule removed nothing, null says nobody counted. On a null, say the exclusion is unmeasured rather than reporting none — the sums themselves are unaffected, and `partial` is what speaks for those. For reproducing the burn tile that is exactly right — it is the conservation law the cash-flow bridge rests on. For "total spend excluding transfers between our own accounts" it is not what the words promise, so say what fell out or leave the flag off. The rule is structural: it counts legs, so no label, category, or type on the row affects it, and a user recategorizing something does not change it. `exempt_categories` takes category keys that should not count. A transaction with no category at all is never matched by an exemption and always stays in the sum; if you want those excluded too, that is a different question and you must say so. `excluded_malformed` counts rows in the window whose amount could not be read as a number. They are in none of the sums, so state the count beside any total rather than presenting a figure that silently skipped them. `partial: true` means the aggregate measured nothing: it was cut short, or no asset account is in scope. Either way it arrives with an empty `rows`, so there is no figure, and the empty rows are not a zero. Say so and offer to try again, unless the workspace holds no deposit or other asset account, where a retry changes nothing. When the token authorizes one workspace, call this directly — no other tool call is needed first. When it authorizes several, this read will not guess which one you mean: pass `workspace_id` on the call.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['from', 'to', 'scope'], 'properties': {'to': {'type': 'string', 'description': 'EXCLUSIVE end of the window, ISO-8601 — the first instant after the last month you want.'}, 'axes': {'type': 'array', 'items': {'enum': ['month', 'currency', 'category', 'ledger_account', 'category_label', 'transaction_type'], 'type': 'string'}, 'maxItems': 6, 'description': 'Group the sums by these, IN ADDITION to currency. Omit for one row per currency over the whole window.'}, 'from': {'type': 'string', 'description': 'Inclusive start of the window, ISO-8601 (e.g. 2026-06-01).'}, 'scope': {'enum': ['own', 'own_and_adopted'], 'type': 'string', 'description': "Which rows are this workspace's: `own` for a sum reconciled against its own balances, `own_and_adopted` for a burn. Required; see the description."}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which."}, 'conversation_id': {'type': 'string', '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.'}, 'exempt_categories': {'type': 'array', 'items': {'type': 'string'}, 'maxItems': 100, 'description': 'Category keys that do not count. An uncategorized row is never matched by one.'}, 'exclude_internal_transfers': {'type': 'boolean', 'description': 'Keeps rows with exactly one leg on an owned account; two-leg transfers AND zero-leg rows (card purchases) both drop. See the description.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['rows', 'window', 'excluded_malformed', 'excluded_zero_leg', 'excluded_multi_leg', 'excluded_no_owned_leg', 'partial', 'rows_truncated', 'success'], 'properties': {'rows': {'type': 'array', 'items': {'type': 'object', 'required': ['month', 'currency', 'category_key', 'ledger_account', 'category_label', 'transaction_type', 'sum_negative', 'sum_positive', 'count_negative', 'count_positive'], 'properties': {'month': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'currency': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'category_key': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'sum_negative': {'type': 'number'}, 'sum_positive': {'type': 'number'}, 'category_label': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'count_negative': {'type': 'number'}, 'count_positive': {'type': 'number'}, 'ledger_account': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'transaction_type': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}}, 'error': {'type': 'string'}, 'window': {'type': 'object', 'required': ['from', 'to'], 'properties': {'to': {'type': 'string'}, 'from': {'type': 'string'}}, 'additionalProperties': False}, 'partial': {'type': 'boolean'}, 'success': {'type': 'boolean'}, 'rows_truncated': {'type': 'boolean'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'excluded_zero_leg': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'excluded_malformed': {'type': 'number'}, 'excluded_multi_leg': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'excluded_no_owned_leg': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_switch_workspace

Switch workspace

Write this conversation's context: the one place its standing choices live. This is the tool the widget cards call when the user CLICKS them: the workspace pin and queue, the selected months, the selected counterparties, and the step acknowledgements are all recorded here, and every later tool call defaults to them. Pass any of: - workspace_ids (ordered list): the workspaces to work in. The FIRST entry becomes the pin and the rest the workspace_queue to work through next. Every id must be one this connection is already authorized for — call well_list_workspaces to see them. This grants no new access; it only chooses among the authorized workspaces. - periods: the months the user VALIDATED on the period card ({ calendar_year, calendar_month } each). Period-scoped reads (well_list_missing_invoices, well_preview_invoice_fetch) default to them when called without a period. Send it only for the user's month selection — never to bound a counterparty pick, which would overwrite that selection. - counterparties: the counterparties (vendors) the user selected, each { company_id, matched_connector_service_id }. Copy both ids off the row you listed them from; pass no display name. The selection belongs to the workspace this call is dispatched to, and a switch to another workspace clears it. One conversation holds one selection, so a new one replaces it; a selection sent for a workspace this conversation has switched away from is REFUSED instead, so a card the flow moved past cannot overwrite the pinned workspace's selection. - counterparty_periods: the months the counterparties card listed, sent alongside counterparties. The pick then narrows those months only, and a month it never covered is read in full. With none named, the months this conversation already holds bound the pick. This never becomes the conversation's selected months. - exempt_categories: the category keys the user marked as NOT burn on the exemption card, copied off what well_list_burn_exemptions returned. An EMPTY list is a real answer and records that they exempted nothing; omit the field entirely when they have not answered yet. The set belongs to the workspace this call is dispatched to, and a switch to another workspace clears it, but a change of months does not, because a category is or is not burn for the business whatever window is read next. One conversation holds one set, so a new one replaces it. - recurring_contexts: the billing context keys the user counts as recurring revenue on the recurring-contexts card, copied off what well_list_recurring_contexts returned. An EMPTY list is a real answer and records that they count nothing as recurring. It is scoped, cleared and replaced exactly like exempt_categories. - counted_account_types: the account types the user ticked as cash on the cash-scope card, copied off what well_list_cash_scope returned. An EMPTY list is a real answer and records that they count nothing as cash, which ends the run rather than reporting a zero total. It is scoped, cleared and replaced exactly like exempt_categories. - ack: "connectors", "bank", "categorize", "assign", "deploy", "invite" or "company_pick": records that the user answered that flow step, in the workspace this call is dispatched to. "company_pick" is the company candidates card's own ack: the card sends it on its Use click alongside the pin to the new company workspace, and on its Keep for later without moving the pin, so you do not send it yourself. "categorize", "deploy", "retarget", "company_pick" and "invite" also take ack_outcome: "done" when the user carried the step out, "keep_for_later" when they set it aside; both end the step. A switch to another workspace clears it, so the next workspace's card asks for its own click. An acknowledgement sent for a workspace this conversation has switched away from is REFUSED instead, so a card the flow moved past cannot un-confirm the step the pinned workspace's own card recorded. - next_step: the line the user picked on the next-steps card, as { skill, prompt } copied off that card's row. The prompt is the sentence the model reads as the user's own message, so it travels beside the slug rather than being rebuilt from it. The pick belongs to the workspace this call is dispatched to, and a switch to another workspace clears it. Call it with NO argument at all to pin the workspace this call itself is dispatched to: its universal workspace_id, or the only workspace the token covers. workspace_ids is the PIN write and nothing else: it moves the pin AND replaces the workspace_queue, so a one-entry list ends a run that still had workspaces queued. Send it only to change the workspace. A call carrying periods, counterparties, exempt_categories, recurring_contexts, counted_account_types, ack or next_step needs no workspace_ids: its universal workspace_id targets that one call, and the pin and the queue stay where they are. Never re-pin the workspace this conversation already holds. Every provided input is applied, and `changed` names the conversation fields this call wrote. `pickup` says what became of the write: "resumed" or "held_then_resumed" mean the model's own turn carries it on and the caller must send no reply of its own, "unwaited" or "exhausted" mean nothing is watching and the caller's reply is the only thing that moves the flow, and "stale" means the flow already answered this card, so the value is kept as a late edit and the caller says nothing. `resumed` is the boolean half of the first two. After a switch, every later call that omits workspace_id targets the pinned workspace, for reads and writes alike; passing workspace_id on a later call overrides it for that call only. well_list_workspaces reports the current conversation context, and well_wait_for_selection reads a card click back, instantly when it already landed here and after a short wait otherwise. This changes nothing in the user's data.

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'ack': {'enum': ['connectors', 'bank', 'categorize', 'assign', 'deploy', 'company_pick', 'accounting_settings', 'retarget', 'invite'], 'type': 'string', 'description': 'Acknowledge a flow step: "connectors" for the connect-tools step, "bank" for the bank step, "categorize" for the counterparty-categorization step, "assign" for the assign-owners step, "deploy" for the collect-agents step, "retarget" for the connector-retarget (data-migration) card, "company_pick" for the company-candidates card, "invite" for the invite-members card. "retarget" is the retarget card\'s own ack: the card sends it on its Confirm with ack_outcome "done", or on its Keep for later with "keep_for_later", so you do not send it yourself. The acknowledgement is scoped to the workspace this call is dispatched to, and a switch to another workspace clears it. An acknowledgement sent for a workspace this conversation has switched away from is refused, and the pinned workspace\'s own acknowledgement of that step stands.'}, 'periods': {'type': 'array', 'items': {'type': 'object', 'required': ['calendar_year', 'calendar_month'], 'properties': {'calendar_year': {'type': 'integer', 'maximum': 2100, 'minimum': 2000, 'description': 'Calendar year, e.g. 2026.'}, 'calendar_month': {'type': 'integer', 'maximum': 12, 'minimum': 1, 'description': 'Calendar month, 1 = January … 12 = December.'}}, 'additionalProperties': False}, 'maxItems': 12, 'minItems': 1, 'description': "The months the user VALIDATED on the period card, stored as this conversation's selected_periods. Later period-scoped reads default to them when called without a period. This field is the user's month selection alone: to bound a counterparty pick, send counterparty_periods instead."}, 'next_step': {'type': 'object', 'required': ['skill', 'prompt'], 'properties': {'skill': {'type': 'string', 'pattern': '^[a-z0-9-]{1,64}$', 'description': 'The slug of the skill the picked line offers, exactly as the card listed it.'}, 'prompt': {'type': 'string', 'maxLength': 160, 'minLength': 1, 'description': 'The sentence the card listed beside the skill, copied as written.'}}, 'description': "The next step the user picked on the well_propose_next_steps card, as the pair that card listed: the skill's slug and the sentence beside it. Both travel, because the sentence is what the model reads as the user's own message and the slug is what it loads. The pick is scoped to the workspace this call is dispatched to, and a switch to another workspace clears it.", 'additionalProperties': False}, 'ack_outcome': {'enum': ['done', 'keep_for_later'], 'type': 'string', 'description': 'What the click said about the step: "done" when the user carried it out, "keep_for_later" when they set it aside on purpose. REQUIRED with ack "categorize" and "deploy" and "retarget" and "company_pick" and "invite", whose cards end on two buttons that mean different things, and refused with every other step, whose card confirms and nothing else.'}, 'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.'}, 'workspace_ids': {'type': 'array', 'items': {'type': 'string', '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)$'}, 'maxItems': 20, 'minItems': 1, 'description': "Ordered workspace selection, and the ONLY field that moves the pin: the FIRST entry becomes this conversation's pin, and the rest REPLACE the workspace_queue, so a one-entry list empties a queue that still holds workspaces. Every entry must be authorized for this connection, or the whole call is refused. Never send it to name the workspace of a periods, counterparties or ack call: the universal workspace_id already targets those, while a re-pin to the id this conversation already holds writes nothing and clears the queue."}, 'counterparties': {'type': 'array', 'items': {'type': 'object', 'required': ['company_id'], 'properties': {'company_id': {'type': 'string', '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)$', 'description': "The counterparty company's id, as listed by well_list_counterparties or well_list_missing_invoices."}, 'matched_connector_service_id': {'anyOf': [{'type': 'string', 'minLength': 1}, {'type': 'null'}], 'description': "The matched provider's connector service id, copied from the row's matched_connector_service_id. Omit or pass null when the row matched no provider; never substitute the provider's name."}}, 'additionalProperties': False}, 'maxItems': 200, 'minItems': 1, 'description': "The counterparties the user selected, stored as this conversation's selected_counterparties and scoped to the workspace this call is dispatched to. At most 200, and a longer list is refused, so a select-all keeps to that bound. Copy the ids off the row: company_id, plus matched_connector_service_id when the row carries one. Send the card's months as counterparty_periods in the same call, so the pick applies to those months only; with none named, the months this conversation already holds bound it. The conversation holds ONE selection, so this REPLACES the previous one, but only when the call names the pinned workspace: a selection sent for a workspace this conversation has switched away from is refused, and the pinned workspace's selection stands."}, 'conversation_id': {'type': 'string', '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.'}, 'idempotency_key': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.'}, 'exempt_categories': {'type': 'array', 'items': {'type': 'string', 'maxLength': 200, 'minLength': 1}, 'maxItems': 100, 'description': "The categories the user marked as NOT burn, stored as this conversation's selected_exemptions and scoped to the workspace this call is dispatched to. Copy each category_key off the row well_list_burn_exemptions returned; never send a label. An EMPTY list is a real answer, since it records that the user exempted nothing, so send it when they clicked Continue with nothing ticked, and omit the field entirely when they have not answered. At most 100, the same bound well_sum_transactions accepts, so a recorded answer is always one the sum can run. The conversation holds ONE set, so this REPLACES the previous one; unlike a counterparty pick it survives a change of months, because a category is or is not burn for the business whatever window is read next."}, 'recurring_contexts': {'type': 'array', 'items': {'type': 'string', 'maxLength': 200, 'minLength': 1}, 'maxItems': 100, 'description': "The billing contexts the user counts as recurring revenue, stored as this conversation's selected_recurring_contexts and scoped to the workspace this call is dispatched to. Copy each context_key off the row well_list_recurring_contexts returned; never send a label. An EMPTY list is a real answer, since it records that the user counts nothing as recurring, so send it when they clicked Continue with nothing ticked, and omit the field entirely when they have not answered. At most 100, the same bound well_render_mrr accepts. The conversation holds ONE set, so this REPLACES the previous one, and like the exemptions it survives a change of months."}, 'counterparty_periods': {'type': 'array', 'items': {'type': 'object', 'required': ['calendar_year', 'calendar_month'], 'properties': {'calendar_year': {'type': 'integer', 'maximum': 2100, 'minimum': 2000, 'description': 'Calendar year, e.g. 2026.'}, 'calendar_month': {'type': 'integer', 'maximum': 12, 'minimum': 1, 'description': 'Calendar month, 1 = January … 12 = December.'}}, 'additionalProperties': False}, 'maxItems': 12, 'minItems': 1, 'description': "The months the counterparties card listed, which bound the pick sent as counterparties in the same call. Send it only with counterparties; it never becomes this conversation's selected months, so it cannot overwrite what the user validated on the period card. With none named, the months this conversation already holds bound the pick."}, 'counted_account_types': {'type': 'array', 'items': {'enum': ['deposit', 'credit', 'loan', 'investment', 'payroll', 'other'], 'type': 'string'}, 'description': "The account types the user ticked as cash, stored as this conversation's selected_cash_scope and scoped to the workspace this call is dispatched to. Copy each account_type off the group well_list_cash_scope returned; never send a label. An EMPTY list is a real answer, since it records that the user counts nothing as cash, which ends the run rather than reporting a zero, so send it when they clicked Continue with nothing ticked, and omit the field entirely when they have not answered. The conversation holds ONE set, so this REPLACES the previous one, and like the exemptions it survives a change of months: a credit card is or is not cash for the business whatever window is read next."}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success', 'resumed', 'pickup'], 'properties': {'error': {'type': 'string'}, 'pickup': {'enum': ['resumed', 'held_then_resumed', 'unwaited', 'exhausted', 'stale'], 'type': 'string', 'description': 'What became of this write: "resumed" (a model wait took it), "held_then_resumed" (no wait yet, so the call was held until one consumed it), "unwaited" (nothing ever consumed it), "exhausted" (the model gave up on the card and ended the turn), "stale" (the flow already answered this card and moved past it — the value is recorded as a late edit). A card prefills a reply on "unwaited" and "exhausted" only.'}, 'changed': {'type': 'array', 'items': {'enum': ['workspace', 'periods', 'counterparties', 'exemptions', 'recurring_contexts', 'cash_scope', 'next_step', 'connectors_ack', 'bank_ack', 'categorize_ack', 'assign_ack', 'deploy_ack', 'company_pick', 'accounting_settings_ack', 'retarget_ack', 'invite_ack'], 'type': 'string'}, 'description': "Which fields of this conversation's context this call wrote."}, 'resumed': {'type': 'boolean', 'description': 'True when the model\'s own turn carries this write on — the derived half of `pickup` ("resumed" or "held_then_resumed"). A card that reads true must not prefill a reply; the conversation continues on its own.'}, 'success': {'type': 'boolean'}, 'warning': {'type': 'string', 'description': 'Present when this call opened a fresh lane because no conversation_id reached it: the write landed, and only a later call that passes the echoed conversation_id back can read it.'}, 'acknowledged': {'enum': ['connectors', 'bank', 'categorize', 'assign', 'deploy', 'company_pick', 'accounting_settings', 'retarget', 'invite'], 'type': 'string'}, 'workspace_id': {'type': 'string'}, 'workspace_name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'workspace_queue': {'type': 'array', 'items': {'type': 'string'}, 'description': 'The workspaces queued after the pinned one, in order.'}, 'selected_periods': {'type': 'array', 'items': {'type': 'object', 'required': ['calendar_year', 'calendar_month'], 'properties': {'calendar_year': {'type': 'integer', 'maximum': 2100, 'minimum': 2000, 'description': 'Calendar year, e.g. 2026.'}, 'calendar_month': {'type': 'integer', 'maximum': 12, 'minimum': 1, 'description': 'Calendar month, 1 = January … 12 = December.'}}, 'additionalProperties': False}}, 'selected_next_step': {'type': 'object', 'required': ['skill', 'prompt'], 'properties': {'skill': {'type': 'string', 'pattern': '^[a-z0-9-]{1,64}$', 'description': 'The slug of the skill the picked line offers, exactly as the card listed it.'}, 'prompt': {'type': 'string', 'maxLength': 160, 'minLength': 1, 'description': 'The sentence the card listed beside the skill, copied as written.'}}, 'description': 'The next step this call recorded, echoed back as the card sent it.', 'additionalProperties': False}, 'selected_cash_scope': {'type': 'array', 'items': {'type': 'string'}}, 'selected_exemptions': {'type': 'array', 'items': {'type': 'string'}}, 'acknowledged_outcome': {'enum': ['done', 'keep_for_later'], 'type': 'string', 'description': 'The answer the acknowledging click carried, echoed back on a step whose card offers two.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}, 'selected_counterparties': {'type': 'array', 'items': {'type': 'object', 'required': ['company_id'], 'properties': {'company_id': {'type': 'string', '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)$', 'description': "The counterparty company's id, as listed by well_list_counterparties or well_list_missing_invoices."}, 'matched_connector_service_id': {'anyOf': [{'type': 'string', 'minLength': 1}, {'type': 'null'}], 'description': "The matched provider's connector service id, copied from the row's matched_connector_service_id. Omit or pass null when the row matched no provider; never substitute the provider's name."}}, 'additionalProperties': False}}, 'selected_recurring_contexts': {'type': 'array', 'items': {'type': 'string'}}}, 'additionalProperties': False}

well_update_company

Update company

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"). CATEGORIES (a counterparty's industry): pass `category_ids` — the COMPLETE set of category ids the company should carry. It REPLACES the current set: ids you leave out are unlinked, and `[]` clears every category. Omit the field to leave the categories untouched. Read the catalog first with well_query_records({ root: "categories", whereClause: { category_type: { _eq: "company" } } }) and pass ids from it — an id that is not a `category_type = "company"` row is refused, and this tool never creates a category. NOT CHANGEABLE via this tool: emails, phones, locations, linked people, media. Those require dedicated tools (not yet available). PROVENANCE: `decision` says HOW the set was chosen. `accepted_suggestion` — the user let a category the classifier had already proposed stand, without touching it. `explicit` — the user chose the labels. **A request the user typed is always an `explicit` choice, so never send `accepted_suggestion` from a conversation.** The affirmation belongs to the categorization card, where a pre-filled picker the reader leaves alone is the only thing that can be let stand; a user who names a category in words has chosen it, even when they say they agree with a suggestion. Omit the field and the write is `explicit`. The server checks an `accepted_suggestion` claim against the company's own pending proposals and returns `explicit` when the written set matches none of them, so the claim can never manufacture classifier provenance. Returns { success: true, company_id, name } on success — plus category_count, the number of categories the company carries afterwards, and decision, the provenance the server settled on, when the call passed `category_ids`. Returns { success: false, error } on failure.

Destructive

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['company_id'], 'properties': {'name': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Company name'}, 'domain': {'anyOf': [{'type': 'string', 'maxLength': 500}, {'type': 'null'}], 'description': 'Primary website domain (e.g. acme.com)'}, 'locale': {'anyOf': [{'enum': ['aa', 'ab', 'ae', 'af', 'ak', 'am', 'an', 'ar', 'as', 'av', 'ay', 'az', 'ba', 'be', 'bg', 'bh', 'bi', 'bm', 'bn', 'bo', 'br', 'bs', 'ca', 'ce', 'ch', 'co', 'cr', 'cs', 'cu', 'cv', 'cy', 'da', 'de', 'dv', 'dz', 'ee', 'el', 'en', 'eo', 'es', 'et', 'eu', 'fa', 'ff', 'fi', 'fj', 'fo', 'fr', 'fy', 'ga', 'gd', 'gl', 'gn', 'gu', 'gv', 'ha', 'he', 'hi', 'ho', 'hr', 'ht', 'hu', 'hy', 'hz', 'ia', 'id', 'ie', 'ig', 'ii', 'ik', 'io', 'is', 'it', 'iu', 'ja', 'jv', 'ka', 'kg', 'ki', 'kj', 'kk', 'kl', 'km', 'kn', 'ko', 'kr', 'ks', 'ku', 'kv', 'kw', 'ky', 'la', 'lb', 'lg', 'li', 'ln', 'lo', 'lt', 'lu', 'lv', 'mg', 'mh', 'mi', 'mk', 'ml', 'mn', 'mr', 'ms', 'mt', 'my', 'na', 'nb', 'nd', 'ne', 'ng', 'nl', 'nn', 'no', 'nr', 'nv', 'ny', 'oc', 'oj', 'om', 'or', 'os', 'pa', 'pi', 'pl', 'ps', 'pt', 'qu', 'rm', 'rn', 'ro', 'ru', 'rw', 'sa', 'sc', 'sd', 'se', 'sg', 'si', 'sk', 'sl', 'sm', 'sn', 'so', 'sq', 'sr', 'ss', 'st', 'su', 'sv', 'sw', 'ta', 'te', 'tg', 'th', 'ti', 'tk', 'tl', 'tn', 'to', 'tr', 'ts', 'tt', 'tw', 'ty', 'ug', 'uk', 'ur', 'uz', 've', 'vi', 'vo', 'wa', 'wo', 'xh', 'yi', 'yo', 'za', 'zh', 'zu'], 'type': 'string'}, {'type': 'null'}], 'description': 'Preferred language as an ISO 639-1 two-letter code (e.g. en, fr, de). Pass null to clear.'}, 'decision': {'enum': ['accepted_suggestion', 'explicit'], 'type': 'string', 'description': 'How the user arrived at `category_ids`. Omit it: a request the user typed is an explicit choice, and accepted_suggestion belongs to the categorization card. See the description.'}, 'company_id': {'type': 'string', '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)$', 'description': 'The UUID of the company to update (required)'}, 'trade_name': {'anyOf': [{'type': 'string', 'maxLength': 100}, {'type': 'null'}], 'description': 'Trading name / DBA'}, 'description': {'anyOf': [{'type': 'string', 'maxLength': 250}, {'type': 'null'}], 'description': 'Brief company description; pass null to clear'}, 'tax_id_type': {'anyOf': [{'type': 'string', 'maxLength': 50}, {'type': 'null'}], 'description': 'Tax identifier type (VAT, SIRET, EIN, ...)'}, 'category_ids': {'type': 'array', 'items': {'type': 'string', '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)$'}, 'maxItems': 20, 'description': 'The COMPLETE set of company-category ids this company should carry. Replaces the current set; [] clears it; omit to leave categories unchanged.'}, 'tax_id_value': {'anyOf': [{'type': 'string', 'maxLength': 255}, {'type': 'null'}], 'description': 'Tax identifier value (VAT, SIRET, EIN, ...)'}, 'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.'}, 'business_type': {'anyOf': [{'type': 'string', 'maxLength': 100}, {'type': 'null'}], 'description': 'Business type / legal form'}, 'registry_name': {'anyOf': [{'type': 'string', 'maxLength': 255}, {'type': 'null'}], 'description': 'Registry name'}, 'conversation_id': {'type': 'string', '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.'}, 'idempotency_key': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.'}, 'registered_name': {'anyOf': [{'type': 'string', 'maxLength': 255}, {'type': 'null'}], 'description': 'Official registered legal name'}, 'registered_value': {'anyOf': [{'type': 'string', 'maxLength': 100}, {'type': 'null'}], 'description': 'Registry identifier value'}, 'registry_country': {'anyOf': [{'type': 'string', 'pattern': '^[A-Z]{2}$', 'maxLength': 2, 'minLength': 2}, {'type': 'null'}], 'description': 'ISO 3166-1 alpha-2 country code of the registry (e.g. FR, US)'}, 'ledger_default_source': {'enum': ['human_override'], 'type': 'string', 'description': 'How the AP/AR pick was made. The only value this write accepts is `human_override`: the person chose the account from the chart of accounts. Optional, and it defaults to `human_override`, so a plain assign needs it not at all.'}, 'account_payable_default_id': {'anyOf': [{'type': 'string', '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': 'null'}], 'description': "The counterparty's default account-payable ledger account (a vendor payable, FR PCG 401). Set it for a counterparty you pay. Omit to leave it; null clears it. Read the ids with `well_list_ledger_accounts`."}, 'account_receivable_default_id': {'anyOf': [{'type': 'string', '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': 'null'}], 'description': "The counterparty's default account-receivable ledger account (a customer receivable, FR PCG 411). Set it for a counterparty that pays you. Omit to leave it; null clears it. Must differ from the payable default."}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'name': {'type': 'string'}, 'error': {'type': 'string'}, 'success': {'type': 'boolean'}, 'decision': {'enum': ['accepted_suggestion', 'explicit'], 'type': 'string'}, 'company_id': {'type': 'string'}, 'category_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_update_invoice

Update invoice

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.

Destructive

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['invoice_id'], 'properties': {'terms': {'anyOf': [{'type': 'string', 'maxLength': 300}, {'type': 'null'}], 'description': 'Payment terms text; pass null to clear'}, 'status': {'enum': ['draft', 'issued', 'paid', 'canceled'], 'type': 'string', 'description': 'Invoice lifecycle status'}, 'due_date': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': 'Payment due date (ISO 8601); pass null to clear'}, 'tax_total': {'anyOf': [{'type': 'number'}, {'type': 'null'}], 'description': 'Total tax amount; pass null to clear'}, 'invoice_id': {'type': 'string', '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)$', 'description': 'The UUID of the invoice to update'}, 'issue_date': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': 'Issue date (ISO 8601, e.g. 2026-04-27); pass null to clear'}, 'description': {'anyOf': [{'type': 'string', 'maxLength': 255}, {'type': 'null'}], 'description': 'Free-form description; pass null to clear'}, 'grand_total': {'anyOf': [{'type': 'number'}, {'type': 'null'}], 'description': 'Total invoice amount including tax; pass null to clear'}, 'items_total': {'anyOf': [{'type': 'number'}, {'type': 'null'}], 'description': 'Sum of line items before tax; pass null to clear'}, 'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.'}, 'local_currency': {'anyOf': [{'type': 'string', 'pattern': '^[A-Z]{3}$', 'maxLength': 3, 'minLength': 3}, {'type': 'null'}], 'description': 'ISO 4217 three-letter currency code (e.g. EUR, USD); pass null to clear'}, 'payment_status': {'enum': ['unpaid', 'partial', 'paid', 'overpaid'], 'type': 'string', 'description': 'User-driven payment_status override — requires override_version (CAS)'}, 'billing_context': {'anyOf': [{'enum': ['subscription', 'recurring', 'periodic', 'installment', 'retainer', 'usage_based', 'consumption', 'metered', 'volume_based', 'overage', 'project', 'milestone', 'hourly', 'fixed_price', 'time_materials', 'one_time', 'event_based', 'commission', 'bonus', 'reimbursement', 'maintenance', 'support', 'consulting', 'training', 'professional_services', 'contract', 'license', 'rental', 'lease', 'franchise', 'adjustment', 'refund', 'credit', 'penalty', 'discount', 'deposit', 'advance_payment', 'escrow', 'insurance', 'tax', 'promotional', 'trial', 'freemium', 'setup', 'activation', 'other', 'mixed', 'unknown'], 'type': 'string'}, {'type': 'null'}], 'description': 'Billing context / business model; pass null to clear'}, 'conversation_id': {'type': 'string', '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.'}, 'idempotency_key': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.'}, 'override_version': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0, 'description': 'Required when payment_status is present — current override_version for CAS'}, 'reference_number': {'anyOf': [{'type': 'string', 'maxLength': 100}, {'type': 'null'}], 'description': 'Invoice reference number (e.g. INV-2026-001); pass null to clear'}, 'issuer_company_id': {'anyOf': [{'type': 'string', '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': 'null'}], 'description': 'Issuer company UUID. Omit = no change, null = clear, uuid = set.'}, 'document_type_code': {'anyOf': [{'enum': ['220', '221', '222', '230', '231', '232', '235', '236', '270', '271', '310', '311', '312', '315', '320', '322', '325', '326', '327', '328', '329', '380', '381', '383', '384', '385', '386', '387', '388', '389', '390', '391', '392', '393', '394', '395', '396', '397', '440', '441', '446', '447', '450', '451', '452', '456', '460', '550', '551', '552', '610', '611', '612', '615', '617', '618', '619', '622', '623', '700', '701', '702', '705', '740', '741', '743', '770', '775', '805', '810', '815', '820', '825', '830', '835', '840', '845', '850', '999'], 'type': 'string'}, {'type': 'null'}], 'description': 'UN/CEFACT 1001 document type code (e.g. 380 for commercial invoice); pass null to clear'}, 'receiver_company_id': {'anyOf': [{'type': 'string', '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': 'null'}], 'description': 'Receiver company UUID. Omit = no change, null = clear, uuid = set.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'error': {'type': 'string'}, 'success': {'type': 'boolean'}, 'invoice_id': {'type': 'string', '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)$'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'reference_number': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_update_person

Update person

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.

Destructive

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['person_id'], 'properties': {'job_title': {'anyOf': [{'type': 'string', 'maxLength': 100}, {'type': 'null'}], 'description': 'Job title; pass null to clear'}, 'last_name': {'type': 'string', 'maxLength': 100, 'minLength': 1, 'description': 'Last name'}, 'person_id': {'type': 'string', '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)$', 'description': 'The UUID of the person to update (required)'}, 'first_name': {'type': 'string', 'maxLength': 100, 'minLength': 1, 'description': 'First name'}, 'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.'}, 'conversation_id': {'type': 'string', '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.'}, 'idempotency_key': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'error': {'type': 'string'}, 'success': {'type': 'boolean'}, 'full_name': {'type': 'string'}, 'person_id': {'type': 'string'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_upload_document

Upload document

Upload a document (invoice, receipt, statement) into the workspace by sending its bytes as base64. ⚠️ THIS IS A WIDGET'S WRITE, NOT YOURS. The card's drop zone reads the file the person dropped or chose, encodes it, and calls this tool itself. Do NOT call it: a model holds no file, so a call made from a conversation can only carry bytes nobody supplied. When a person says they have the invoice, point them at the drop zone on the gap card. Send `content_base64` WITHOUT a data-URI prefix — the raw base64 only, no `data:application/pdf;base64,` header. Accepted content: PDF, JPEG, PNG, GIF, HEIC, HEIF, AVIF, WEBP, TIFF, plain text, CSV, XML. The bytes are checked against the declared `mime_type` (file signature, not just the claim), so a PNG announced as a PDF is refused. Size ceiling: 5 MB of file (before base64). A larger file is refused with its actual size — upload it through the web app instead, which accepts up to 15 MB. Pass `source_transaction_id` to anchor the document to the bank transaction it pays. That is what makes a dropped invoice land on the right line instead of in a general inbox. Well extracts the document after upload; the extraction is asynchronous and this call returns as soon as the file is stored. A file already in the workspace is deduplicated by content and returns the existing document rather than a copy.

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['filename', 'mime_type', 'content_base64'], 'properties': {'filename': {'type': 'string', 'minLength': 1, 'description': "The file's name WITH its extension, e.g. `invoice-2026-03.pdf`. The extension resolves the content type when `mime_type` is generic."}, 'mime_type': {'type': 'string', 'minLength': 1, 'description': "The file's content type, e.g. `application/pdf`. Send `application/octet-stream` when unknown and the extension decides."}, 'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.'}, 'content_base64': {'type': 'string', 'minLength': 1, 'description': "The file's bytes, base64, with no data-URI prefix."}, 'source_task_id': {'type': 'string', '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)$', 'description': 'The task this document answers.'}, 'conversation_id': {'type': 'string', '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.'}, 'idempotency_key': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.'}, 'source_transaction_id': {'type': 'string', '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)$', 'description': 'The bank transaction this document is the proof for.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'error': {'type': 'string'}, 'outcome': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'success': {'type': 'boolean'}, 'filename': {'type': 'string'}, 'max_bytes': {'type': 'number'}, 'mime_type': {'type': 'string'}, 'error_code': {'type': 'string'}, 'size_bytes': {'type': 'number'}, 'document_id': {'type': 'string'}, 'actual_bytes': {'type': 'number'}, 'deduplicated': {'type': 'boolean'}, 'source_task_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'source_transaction_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_upload_statement_bytes

Upload statement bytes

Upload a bank statement file's BINARY CONTENT (PDF or image) as base64, so the file's real bytes reach Well without any out-of-band HTTP call. Use it for PDF and image statements up to 5 MiB decoded (the base64 text may be roughly a third larger). Base64-encode the file's bytes EXACTLY — never re-encode a screenshot, a transcription, or a summary of the file. Optionally send the file's sha256 (hex); the server decodes, hashes, and rejects a mismatch, proving the bytes arrived intact. The response carries content_sha256 and byte_length of the decoded payload — report them for verification. The parsed rows, totals, and import outcome arrive via well_get_statement_import_result with the returned document_id. Text statements (.csv/.txt/.xml) whose contents are verbatim in this conversation can go through well_upload_statement_content instead. Upload one statement file per call — call this tool once per file. The document enters the same import pipeline as an in-app upload (detection, dedup, promotion).

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['filename', 'content_base64'], 'properties': {'sha256': {'type': 'string', 'pattern': '^[0-9a-fA-F]{64}$', 'description': "The source file's SHA-256 (hex). When sent, a mismatch with the decoded bytes rejects the upload."}, 'filename': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'The statement\'s file name, e.g. "statement.csv". Only its extension selects the format.'}, 'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.'}, 'content_base64': {'type': 'string', 'minLength': 1, 'description': "The file's bytes, base64-encoded (RFC 4648; whitespace tolerated). Decoded cap: 5 MiB."}, 'conversation_id': {'type': 'string', '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.'}, 'idempotency_key': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'error': {'type': 'string'}, 'success': {'type': 'boolean'}, 'byte_length': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'document_id': {'type': 'string', 'description': 'Poll well_get_statement_import_result with this id for the import outcome.'}, 'deduplicated': {'type': 'boolean', 'description': 'True when an identical document was already in the workspace — nothing was imported twice.'}, 'content_sha256': {'type': 'string', 'description': 'SHA-256 (hex) of the payload the server received — compare against your source to verify fidelity.'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_upload_statement_content

Upload statement content

Upload a bank statement's TEXT CONTENT (a .csv, .txt, or .xml file) directly, as an alternative to well_create_statement_upload's out-of-band file POST. Use it when the user's statement is a small text file whose contents are verbatim in this conversation (1 MiB decoded limit). Send the content EXACTLY as you received it — never reformat, summarize, transcribe from memory, or reconstruct rows. A mangled relay imports wrong financial data. This path is BEST-EFFORT fidelity: what Well ingests is what you relayed, not a byte-verified copy of the user's file. The response carries content_sha256 and byte_length of what the server received — report them so a corrupted relay is visible. The parsed rows, totals, and import outcome arrive via well_get_statement_import_result with the returned document_id, not in this response. PDFs and images NEVER go here (the model cannot relay their bytes faithfully) — use well_upload_statement_bytes. XML with DOCTYPE/ENTITY declarations is rejected. Upload one statement file per call — call this tool once per file. The document enters the same import pipeline as an in-app upload (detection, dedup, promotion).

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['filename', 'content_text'], 'properties': {'filename': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'The statement\'s file name, e.g. "statement.csv". Only its extension selects the format.'}, 'content_text': {'type': 'string', 'minLength': 1, 'description': "The file's full text content, verbatim. UTF-8 encoded on the wire; capped at 1 MiB decoded."}, 'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.'}, 'conversation_id': {'type': 'string', '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.'}, 'idempotency_key': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'error': {'type': 'string'}, 'success': {'type': 'boolean'}, 'byte_length': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'document_id': {'type': 'string', 'description': 'Poll well_get_statement_import_result with this id for the import outcome.'}, 'deduplicated': {'type': 'boolean', 'description': 'True when an identical document was already in the workspace — nothing was imported twice.'}, 'content_sha256': {'type': 'string', 'description': 'SHA-256 (hex) of the payload the server received — compare against your source to verify fidelity.'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

well_upsert_accounting_settings

Set accounting settings

Set the workspace's accounting settings: fiscal year start month, first fiscal year start date, country, base currency, accounting framework, chart-of-accounts confirmation, the incorporation date, and the tax ID (value and type together). Provide only the fields you are changing; omitted fields are left untouched. An empty call (no fields) is refused. tax_id_value and tax_id_type must be provided together. Only a workspace owner or admin may set the accounting settings. A caller without that role is refused, not silently ignored. Changing the fiscal year start month moves the whole fiscal calendar, so it is REFUSED when a period is locked or a close is in progress — the tool surfaces that refusal rather than forcing it. When the change is allowed, it soft-deletes the workspace's regenerable DRAFT journal entries so they re-mint on the new coordinates; VALIDATED and LOCKED entries are never touched. These are accounting-critical values. Confirm each one with the user before calling and never guess them — do not infer a country, currency, framework, start month, or tax ID the user did not state. The tax ID here updates the workspace's anchored company and its settings mirror together, so the two never drift. To set WHICH company is anchored, use well_set_own_company; to set that company's tax ID, use this tool.

Destructive

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'country': {'type': 'string', 'maxLength': 2, 'minLength': 2, 'description': 'ISO 3166-1 alpha-2 country code.'}, 'tax_id_type': {'type': 'string', 'description': "The tax id's type (SIREN, VAT, EIN, …). Provide it together with tax_id_value."}, 'tax_id_value': {'type': 'string', 'maxLength': 50, 'minLength': 1, 'description': "The company's tax id value. Provide it together with tax_id_type; one without the other is refused."}, 'workspace_id': {'type': 'string', '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)$', 'description': 'Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.'}, 'base_currency': {'type': 'string', 'maxLength': 3, 'minLength': 3, 'description': 'ISO 4217 currency code.'}, 'coa_confirmed': {'type': 'boolean', 'description': 'Whether the chart of accounts has been confirmed.'}, 'conversation_id': {'type': 'string', '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.'}, 'idempotency_key': {'type': 'string', 'maxLength': 255, 'minLength': 1, 'description': 'Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.'}, 'incorporation_date': {'anyOf': [{'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$'}, {'type': 'null'}], 'description': "The company's incorporation / registration date as YYYY-MM-DD, or null to clear it."}, 'accounting_framework': {'enum': ['PCG', 'IFRS', 'US_GAAP', 'SKR'], 'type': 'string', 'description': 'The accounting framework the books follow.'}, 'fiscal_year_start_month': {'anyOf': [{'type': 'integer', 'maximum': 12, 'minimum': 1}, {'type': 'null'}], 'description': 'Calendar month (1-12) the fiscal year starts on, or null to clear it.'}, 'first_fiscal_year_start_date': {'anyOf': [{'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$'}, {'type': 'null'}], 'description': 'First fiscal year start date as YYYY-MM-DD, or null to clear it.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'error': {'type': 'string'}, 'country': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'success': {'type': 'boolean'}, 'tax_id_type': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'tax_id_value': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'base_currency': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'coa_confirmed': {'anyOf': [{'type': 'boolean'}, {'type': 'null'}]}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'incorporation_date': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'accounting_framework': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}, 'fiscal_year_start_month': {'anyOf': [{'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, {'type': 'null'}]}, 'first_fiscal_year_start_date': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}

well_wait_for_selection

Wait for selection

Read the user's card click, holding the turn open until it lands. Call it in the SAME turn, right after the tool whose card asks the user to click: well_list_workspaces (kind "workspace"), well_list_periods (kind "periods"), well_list_missing_invoices (kind "counterparties" — its card is the only one that records a counterparty pick), well_list_burn_exemptions (kind "exemptions"), well_list_recurring_contexts (kind "recurring_contexts"), well_list_cash_scope (kind "cash_scope"), well_list_connectors (kind "connect_ack" for the connect step, "bank_ack" for the bank step), well_list_counterparties (kind "categorize_ack" — its Continue and its Keep for later both write it), well_list_missing_invoice_owners (kind "assign_ack" — its Continue writes it), well_preview_invoice_fetch (kind "deploy_ack" — its Deploy, its Continue and its Keep for later all write it), well_show_company_candidates (kind "company_pick" — its Use this company mints the company workspace, switches into it and writes the ack in one call; its Keep for later writes the same ack with the outcome the click carried and moves no pin), well_show_retargetable_connectors (kind "retarget_ack" — its Confirm and its Keep for later both write it, with the outcome the click carried), well_list_member_candidates (kind "invite_ack" — its Send and its Keep for later both write it, with the outcome the click carried), or well_propose_next_steps (kind "next_step": a row click writes it; on "selected", take selection.next_step.prompt as the user's own message and start that skill in the same turn, loading it with well_get_skill). It waits up to 60s for the click. "selected" — continue the flow. "no_selection_yet" — call it again at once, at most 5 calls in this turn; after the fifth, end the turn on the card in one line, and the user's click then prefills the reply that resumes the flow. - status "selected": the choice is recorded. `selection` carries it — the pinned workspace_id and workspace_queue, the picked periods, the picked counterparties (each { company_id, matched_connector_service_id } plus the workspace_id they belong to and the `periods` they were listed for), the exempted category keys or the recurring context keys plus the workspace_id they belong to, or the acknowledgement plus the workspace_id it was made in and, on a card whose buttons say different things, the `outcome` the click carried. `already_set: true` means it was recorded since the card was drawn but before this call (the user had already clicked). Continue the flow with it. Only a click recorded SINCE the card was drawn is reported. An answer left over from an earlier conversation stays in the session and is never handed back, so this tool always waits for the click the card in front of the user is asking for. - status "no_selection_yet": nothing has been recorded since the card was drawn and no click landed within the wait (default 60s, clamped 5-60s). This is a NORMAL result, not an error. Call this tool again at once, up to 5 calls in one turn. After the fifth, end the turn on the card in one line; the user's click then prefills the reply that resumes the flow. A counterparty pick belongs to the workspace AND the months it was made against, and it carries those months in `selection.periods`. A switch to another workspace, a change of the selected months, or a fresh well_list_missing_invoices card drops it. So kind "counterparties" never hands back a pick made against another month: with that pick dropped, the call waits for the new click instead. A pick recorded BEFORE this call is reported only when it was made in the workspace this call targets, so pass `workspace_id` to ask about a workspace the conversation is not switched to. A pick that lands DURING the wait rides back with the workspace it was made in. Compare `selection.workspace_id` before you act on it. A burn-exemption answer belongs to the workspace it was made in and rides back as `selection.workspace_id`, and it carries no months: a category is or is not burn for the business, so the same answer holds over any window. An EMPTY `selection.exempt_categories` on status "selected" means the user exempted NOTHING — act on it, do not re-ask. A switch to another workspace drops it; a change of the selected months does not. A recurring-contexts answer follows the same rules as a burn-exemption answer: it belongs to the workspace it was made in, carries no months, and an EMPTY `selection.recurring_contexts` on status "selected" means the user counts NOTHING as recurring — act on it, do not re-ask. A cash-scope answer follows those same rules, and its empty case is the one to read carefully: an EMPTY `selection.counted_account_types` on status "selected" means the user counts NOTHING as cash. That is a resolution, not a scope of size zero — say there is no cash position left to report and END the run, rather than carrying an empty scope into a total the renderer cannot draw. Kind "cash_scope" is the reader's ANSWER — the account types they ticked, and nothing else. It is not `well_render_cash_forecast`'s `cash_scope` field, which is the fuller policy an answer feeds into (the counted types plus the ownership and exclusion counts the caller measured). An acknowledgement belongs to the workspace it was made in, and rides back as `selection.workspace_id`. On kinds "categorize_ack", "deploy_ack", "retarget_ack", "company_pick" and "invite_ack" it also carries `selection.outcome`: "done" means the user carried the step out, "keep_for_later" means they set it aside. Both end the step, so continue the flow either way and say in half a sentence which one it was. A switch to another workspace drops it. An ack recorded BEFORE this call is reported only when it was made in the workspace this call targets, so pass `workspace_id` to ask about a workspace the conversation is not switched to. A click that lands DURING the wait is reported with its own workspace, which can be another card's. Compare `selection.workspace_id` before you act on it. This tool reads and waits — it changes nothing.

Read only

Input schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['kind'], 'properties': {'kind': {'enum': ['workspace', 'periods', 'counterparties', 'exemptions', 'recurring_contexts', 'cash_scope', 'connect_ack', 'bank_ack', 'categorize_ack', 'deploy_ack', 'assign_ack', 'accounting_settings_ack', 'next_step', 'company_pick', 'retarget_ack', 'invite_ack'], 'type': 'string', 'description': 'Which card click to wait for: "workspace" (the workspace picker\'s Use), "periods" (the month picker\'s Validate), "counterparties" (the missing-invoices card\'s Continue), "exemptions" (the burn-exemption card\'s Continue), "recurring_contexts" (the recurring-contexts card\'s Continue), "cash_scope" (the cash-scope card\'s Continue), "accounting_settings_ack" (the accounting-settings card\'s Confirm), "connect_ack" / "bank_ack" (the connect card\'s Continue), "categorize_ack" (the categorize card\'s Continue or Keep for later), "assign_ack" (the owner-assignment card\'s Continue), "deploy_ack" (the collect-agents card\'s Deploy, Continue or Keep for later), "company_pick" (the company-candidates card\'s Use this company or Keep for later), "invite_ack" (the invite-members card\'s Send or Keep for later), "retarget_ack" (the connector-retarget card\'s Confirm or Keep for later), "next_step" (a row click on the next-steps card).'}, 'timeout_s': {'type': 'number', 'description': 'How long to wait, in seconds. Default 60, clamped to 5-60.'}, 'workspace_id': {'type': 'string', '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)$', 'description': "Target workspace. This read reports one workspace's own data. Omit it and the token's primary workspace answers, which may not be the one you mean; the result names the workspace that did."}, 'waiting_notice': {'type': 'string', 'maxLength': 120, 'minLength': 1, 'description': 'One short line the person reads while this call holds the turn open, IN THE LANGUAGE THEY ARE WRITING IN. Say what you are waiting for them to do on the card, in your own words, not what the server is doing: they are the one holding the flow. Omitted falls back to an English line, which a reader working in another language may not read, so write it whenever you know their language.'}, 'conversation_id': {'type': 'string', '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.'}}, 'additionalProperties': False}

Output schema

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['success'], 'properties': {'hint': {'type': 'string'}, 'kind': {'enum': ['workspace', 'periods', 'counterparties', 'exemptions', 'recurring_contexts', 'cash_scope', 'connect_ack', 'bank_ack', 'categorize_ack', 'deploy_ack', 'assign_ack', 'accounting_settings_ack', 'next_step', 'company_pick', 'retarget_ack', 'invite_ack'], 'type': 'string'}, 'error': {'type': 'string'}, 'status': {'enum': ['selected', 'no_selection_yet'], 'type': 'string'}, 'success': {'type': 'boolean'}, 'selection': {'type': 'object', 'properties': {'outcome': {'enum': ['done', 'keep_for_later'], 'type': 'string', 'description': 'What the acknowledging click said about the step: "done" when the user carried it out, "keep_for_later" when they set it aside on purpose. Both end the step and continue the flow. Absent on a card whose one action confirms and nothing else.'}, 'periods': {'type': 'array', 'items': {'type': 'object', 'required': ['calendar_year', 'calendar_month'], 'properties': {'calendar_year': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'calendar_month': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}}, 'additionalProperties': False}, 'description': 'The picked months on kind "periods"; the months the picked counterparties were listed for on kind "counterparties" — empty when the pick names none and so applies to every month read.'}, 'next_step': {'type': 'object', 'required': ['skill', 'prompt'], 'properties': {'skill': {'type': 'string', 'description': 'The slug of the skill the picked row offers.'}, 'prompt': {'type': 'string', 'description': "The sentence the picked row carried, to be treated as the user's own message."}}, 'description': 'The row the user picked on kind "next_step".', 'additionalProperties': False}, 'acknowledged': {'type': 'boolean', 'const': True}, 'workspace_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'description': 'The pinned workspace on kind "workspace"; the workspace the picked counterparties belong to; the workspace the acknowledgement was made in.'}, 'counterparties': {'type': 'array', 'items': {'type': 'object', 'required': ['company_id'], 'properties': {'company_id': {'type': 'string'}, 'matched_connector_service_id': {'type': 'string', 'description': "The matched provider's connector service id; absent when the picked row matched no provider."}}, 'additionalProperties': False}}, 'workspace_queue': {'type': 'array', 'items': {'type': 'string'}}, 'exempt_categories': {'type': 'array', 'items': {'type': 'string'}, 'description': 'The category keys the user marked as NOT burn on kind "exemptions". An EMPTY array is the answer "nothing is exempt", not an absent one — status "selected" is what says the user answered.'}, 'recurring_contexts': {'type': 'array', 'items': {'type': 'string'}, 'description': 'The billing context keys the user counts as recurring on kind "recurring_contexts". An EMPTY array is the answer "nothing is recurring", not an absent one.'}, 'counted_account_types': {'type': 'array', 'items': {'type': 'string'}, 'description': 'The account types the user counts as cash on kind "cash_scope". An EMPTY array is the answer "nothing counts as cash", not an absent one — it ends the run rather than reporting a zero total.'}}, 'description': 'The value the click wrote. Present only when status is "selected".', 'additionalProperties': False}, 'already_set': {'type': 'boolean', 'description': 'True when the click had already been recorded since the card was drawn, before this call started — no wait happened.'}, 'conversation_id': {'type': 'string', 'description': 'The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.'}, 'resolved_workspace': {'type': 'object', 'required': ['workspace_id', 'name'], 'properties': {'name': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'workspace_id': {'type': 'string'}}, 'description': 'The workspace that answered, when the caller named none and the token authorizes several.', 'additionalProperties': False}, 'conversation_id_note': {'type': 'string', 'description': 'Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.'}, 'conversation_id_source': {'enum': ['host_meta', 'argument', 'minted'], 'type': 'string', 'description': "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened."}}, 'additionalProperties': False}

Well

What this MCP does

Tools

Recent tool changes

Similar MCP servers

Lovie Company Formation

Stratalize Finance

Red by Big Red Cloud

GestãoClick

Superlógica Condomínios

FalaZuki Finance BR

XBOSS

Sirenic