Declare a counterparty's default transaction category
well_set_counterparty_default_categoryDeclare 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
| Name | Required | Description | Default |
|---|---|---|---|
| category | Yes | The category label spend at this counterparty defaults to. Must be one of the labels in this list. | |
| company_id | Yes | The counterparty to declare a default for, from well_list_counterparties. | |
| workspace_id | No | 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 | No | 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 | No | Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | ||
| success | Yes | ||
| category | No | The label the counterparty's default now carries. | |
| company_id | No | ||
| company_name | No | ||
| conversation_id | No | 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 | No | Present only when the server opened a fresh lane, stating that no choice recorded earlier was read. | |
| conversation_id_source | No | Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened. |