Render a caller-computed cash position
well_render_cash_positionPut 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 checks the scope against the saved cash scope and refuses a mismatch; computed_by: "caller" covers only the total's arithmetic.
The server derives no cash figure of its own here, so every input in the REQUIRED list must state the policy behind the number and make it checkable.
The result includes unsettled_ownership, the server-derived number of accounts whose owner is unanswered. Do not send it as an input; the server returns it with the figure.
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:
amountandcurrency— 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 foraccounts— every account that CONTRIBUTED, each with its native amount and currency, the converted amount, and the rate applied (nullwhen it was already incurrency). Carryinstitution_nameandmasked_account_numberthrough 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 bothnull, and never by its id.scope: the account types you counted as cash, and whether you counted an account whose ownership tag is unknown but which the workspace marks as ownedexcluded: the groups that fell out, by reason: not owned, out-of-scope type, no readable balance, or no FX rate. An unanswered owner belongs to no group; the result carries its count asunsettled_ownership. 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 a balance or FX rate was missing, the own-company set was truncated, or some account's ownership is unsettled. It never means a cut-short read: that stops before this call.own_set_truncated, when true — the balance read reached the own-company row cap. Keep the known ownership verdicts, render their total, and state that it is partial.
REFUSED rather than rendered when one of these checks fails:
the caller's
scope,accountsorexcludedcounts differ from the server's check of the saved cash scope. The workspace may have changed since the reads: re-readwell_list_cash_scopeandwell_list_account_balances, then recompute from the latest results instead of changing the arithmetic to fit.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
a rate more than 1% away from Well's stored rate for the pair as of
as_of, or a rate for a pair Well stores no rate for (count those accounts inexcluded.no_fx_rate). Read rates fromexchange_rates; never estimate one.a failure to read the workspace cash scope or balances. A failed stored-rate read is not a refusal: the call fails with a service-side error, and a failed read is never a missing rate.
an account already in
currencythat carries a rate other than one, or whose converted amount differs from its native onean account in another currency that states no rate
the same account contributing twice
a non-zero total with no contributing accounts
an
as_ofin the futurea
covers_daythat is not the last day of its month — this tool uses it to read a complete month-end balancea
covers_daythat is not the dayas_offalls ona
scope.account_typesnaming nothinga
balance_historythat repeats a month or runs out of ordera currency outside ISO-4217 — checked against the catalog, not its shape
OPTIONAL:
covers_day— the UTC day the figure covers,YYYY-MM-DD. A month-end reading covers the last day of that month, andas_ofMUST be that day's close,<day>T23:59:59Z. Anything earlier is refused: every rate is checked as ofas_ofand the stored rate is the latest one on or before it, so a figure covering August stamped earlier in the day converts at the previous day's rate under a caption that says otherwise. A live reading covers no day, so leave the field off — sending it there is an error this tool cannot catch, and it costs the reader the resolution into their own zone that a live reading is meant to get. The card draws a covered day as written, and it cannot tell a covered day from a live moment out ofas_ofalone: a day's close lands at23:59:59Z, so every reader east of UTC sees the NEXT day unless you send this.balance_history— trailing complete month ends, oldest first. Anullamount 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.
OPTIONAL, and send it whenever you computed a cash-flow bridge over the same cash:
cash_bridge—{ unexplained, closing }, the two terms you sentwell_render_cash_flow_bridge, in this card's currency. The server applies the bridge's own tolerance and returnscash_check."provisional": the bridge does not reconcile, the gap is inunexplained_gap, and the card marks the figure Provisional; say so in prose too: the figure stands on cash with an unexplained gap of that amount."reconciled": say nothing about it. Leavecash_bridgeoff when you computed no bridge: the result iscash_check: "not_checked"and the card marks the figure Not checked.
When the token authorizes one workspace, call this directly — no workspace 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 |
|---|---|---|---|
| as_of | Yes | ||
| scope | Yes | ||
| amount | Yes | ||
| partial | Yes | ||
| accounts | Yes | ||
| currency | Yes | ||
| excluded | Yes | ||
| covers_day | No | ||
| cash_bridge | No | The cash-flow bridge over the same cash, when you computed one. The server decides whether it reconciles and returns the figure's `cash_check`. Leave it off when you computed no bridge: the figure is then `not_checked`. | |
| workspace_id | No | 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 | No | ||
| 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. | |
| workspace_scope | No | Restrict this call to the family: the token's primary workspace plus the company workspaces under it that you are a member of. Unrelated authorized workspaces drop out of the read; row reads merge across the family, while a per-workspace figure still reports exactly one workspace. | |
| own_set_truncated | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| as_of | Yes | ||
| scope | Yes | ||
| amount | Yes | ||
| partial | Yes | ||
| success | Yes | ||
| accounts | Yes | ||
| currency | Yes | ||
| excluded | Yes | ||
| cash_check | No | ||
| covers_day | No | ||
| computed_by | Yes | ||
| balance_history | 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. | |
| newly_connected | No | Tools that connected to this workspace since the last result and that no session was told about yet, oldest first. Present only when at least one tool is new. The connected-line rule says when to tell an entry; when it does, one line per entry, in the person's language: "<name> is connected.". Never fold several entries into one sentence. Each entry comes back once, on one result only: never repeat its line later. | |
| unexplained_gap | No | ||
| own_set_truncated | No | ||
| resolved_workspace | No | The workspace that answered, when the caller named none and the token authorizes several. | |
| unsettled_ownership | No | ||
| 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. |