Get exchange rate
well_get_fx_quoteCall this FIRST for any question about an exchange rate or a currency conversion, in any wording or language ("convert 500 EUR to USD", "how much is 2,000 GBP in euros", "EUR USD today", "what's the dollar at", "and in GBP?"): your own memory of rates is out of date and wrong, so never answer a rate or a converted figure without this call, and never answer it from a web search or from your own arithmetic.
Convert an amount between two currencies, or read the exchange rate: how many quote one base is worth on a day. Use it in any workflow that needs a rate or a converted figure (converting an amount, pricing an invoice in another currency, reading a balance or a report in one currency), so the rate and the arithmetic come from Well and are never typed, recalled, estimated or computed by you. The rate is a daily reference rate from the provider source names (Well reads more than one): it is not a live market quote, and a live rate can differ slightly.
Pass base and quote as ISO 4217 codes, always both. Pass amount, a plain decimal string such as "500.00" (no currency symbol, no thousands separator), whenever there is a sum to convert: the tool multiplies and rounds it, so never multiply an amount by a rate yourself. Do not call the tool when base and quote are the same currency: nothing converts, so the amount stands as it is. Leave amount out only when you need the rate alone; it then defaults to "1". Pass date (YYYY-MM-DD) for the day the rate must hold on, such as a document's issue date; leave it out for today. Any day since 4 January 1999 has a rate, so never tell the person that history is limited or that old dates are unavailable: ask for the date and read the answer.
Returns status. "same_currency": base equals quote (a call that should not have been needed), nothing converts, and converted_amount is the amount. "found": amount, converted_amount (the amount in quote, rounded to that currency's minor units: quote it exactly as given) and converted_currency; rate ("1 base = rate quote") and inverse_rate (1 quote in base), decimal strings to quote as given; rate_date (the day of the latest rate published on or before date); source (the provider of the rate); and triangulated (true when two published rates were combined through EUR). To state the rate, quote rate, not a converted_amount for an amount of 1, which is rounded. "no_rate": reason is "no_rate_on_or_before_date" (no published rate on that date or in the week before it), "before_rate_history" (the date is before the first rate Well holds), "unsupported_pair" (no provider publishes a rate for a currency) or "provider_unavailable" (the rate source did not answer in time; a retry in a moment can work), with a plain message you can pass on as it is. A malformed, negative or oversized amount is refused with error_reason "invalid_amount".
On "no_rate", say that no rate was available and stop: never state, estimate or recall a rate or a converted figure yourself. Say, in one short plain sentence, that the rate is the source reference rate of rate_date, not a live market rate, beside any rate or converted figure you show. Quote source and rate_date exactly as returned, never another provider's name. When rate_date differs from date, state rate_date only, never a reason for the gap (a weekend, a holiday, a publication time).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| base | Yes | The currency being converted from: 1 base = rate quote. | |
| date | No | The day the rate must hold on, YYYY-MM-DD. Leave out for today. | |
| quote | Yes | The currency being converted to. | |
| amount | No | The sum of `base` to convert, a decimal string such as "500.00". Leave out to get the rate alone: it defaults to "1". | 1 |
| workspace_id | No | Target workspace. Optional: this tool describes the token itself rather than one workspace's data, so omitting it returns the same answer. | |
| 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. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| base | No | ||
| rate | No | 1 base in quote, a decimal string. | |
| error | No | ||
| quote | No | ||
| amount | No | The sum of base that was converted, as given. | |
| reason | No | ||
| source | No | ||
| status | No | ||
| message | No | On no_rate, a plain sentence saying why, to pass on to the person. | |
| success | Yes | ||
| rate_date | No | The day the rate was published. | |
| error_reason | No | ||
| inverse_rate | No | 1 quote in base, a decimal string. | |
| triangulated | No | ||
| requested_date | 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. | |
| converted_amount | No | The amount in quote, rounded to its minor units: quote it as given. | |
| converted_currency | 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. |