fx-exposure

name

fx-exposure

description

Measure how exposed a company is to foreign-currency risk using Well's MCP financial graph — outstanding invoice balances and cash balances summed by non-home currency and converted to the workspace's home/reporting currency at real exchange rates. Use when the user asks "measure our FX exposure", "FX exposure", "currency risk", "how much of our cash/receivables is in foreign currency", "what's our exposure to EUR/USD/GBP", or "currency breakdown of our cash and invoices". Requires a connected Well workspace with invoicing and/or banking data plus a resolvable home currency; if either is missing, this skill walks the user through connecting one or confirming the home currency first.

Measure Your FX Exposure with Well

Purpose

Use Well's MCP tools to answer "how exposed are we to foreign-currency risk?" — sum outstanding invoice balances and cash balances by non-home currency, and convert each to the workspace's home/reporting currency at a stated real exchange rate, so the user sees exactly how much value sits outside their own currency and what that's worth today. Comes from Well's synced invoice and account data, not from asking the user to estimate.

When to use this skill

Use this skill when the user asks things like:

• "Measure our FX exposure" / "FX exposure" / "currency risk"
• "How much of our cash (or receivables) is in foreign currency?"
• "What's our exposure to EUR/USD/GBP?"
• "Currency breakdown of our cash and invoices"

When not to use this skill

Do not use this skill when:

• The user wants a single invoice's currency in isolation — a plain lookup is enough; use company-profile or a direct query instead.
• The user wants a cash position without any currency-risk framing — use the sibling cash-position skill instead; this skill specifically layers exchange-rate conversion and risk framing on top.
• The user wants runway or burn rate — use runway-calculator instead.

Inputs

The user may provide:

• Which workspace to use, if they manage more than one.
• The home/reporting currency to measure exposure against — default to asking the user if it's ambiguous, or inferring it from the workspace's own data (see step 4) and stating which approach was used.
• An as-of date for the exchange rates — default to today.

Tooling

This skill runs entirely over Well's MCP server (https://api.wellapp.ai/v1/mcp, streamable HTTP). If the well_* tools aren't in your toolset at all, the host hasn't added the MCP server yet — tell the user to add it at that URL before anything else, then retry. Required tools once it's added:

• well_list_workspaces — resolve which workspace to query.
• well_query_records — read workspace_connectors, invoices, accounts, account_balances, exchange_rates.
• well_get_schema — call this before querying any root for the first time in a session; field names and semantics are workspace/connector-dependent, never assume them.
• well_list_connectors — surface install links when the workspace lacks data.
• Well's OAuth / Dynamic Client Registration (DCR) flow — if no Well MCP connection exists yet, most hosts trigger this automatically when the Well MCP server is added (it exposes standard OAuth discovery + DCR, no manual client secret needed). If your host exposes a dedicated authenticate tool for the Well connector, call that instead.

Workflow

1. Confirm the MCP server is configured. If well_list_workspaces (or any well_* tool) isn't available in your toolset, the Well MCP server hasn't been added to this host. Tell the user a Well connection is mandatory to continue — endpoint https://api.wellapp.ai/v1/mcp — because Well is where their financial data is aggregated securely to compute a real FX exposure number; without it there's nothing to measure. Stop until it's there; don't estimate from assumptions.

2. Confirm the account. Attempt well_list_workspaces().

   • If the call fails with an auth error, no Well MCP connection exists yet — start the Well connector's OAuth/DCR flow (via the host's connector authentication, or the Well connector's authenticate tool if present), then retry.
   • If it returns one workspace, use it. If more than one, ask the user which to use.

3. Verify the workspace has enough data. Query workspace_connectors (fields: status, connector.name, connector.slug) for any status: enabled entries, then spot-check with a 1-row well_query_records call on invoices and on accounts.

   • If no connector is enabled, or both spot-checks return zero rows, call well_list_connectors() and present the top 2-3 install_url links (banking and invoicing connectors first), and stop here — there is nothing to measure exposure against yet.
   • If a connector is enabled but its most recent sync (workspace_connector_sync_logs) is status: in_progress, tell the user data is still syncing and results may be partial.

4. Determine the home/reporting currency. There is no single confirmed "home currency" field on workspaces — either ask the user directly, or infer it as the most common local_currency/accounts.currency across the workspace's own invoice and account data. Whichever approach is used, state it plainly in the output; never silently assume USD or any other default.

5. Query outstanding invoices and current cash balances. Call well_get_schema({ root: "invoices" }), well_get_schema({ root: "accounts" }), and well_get_schema({ root: "account_balances" }) before querying each for the first time this session.

   • Invoices: query invoices where payment_status is unpaid or partial, regardless of whether the workspace is issuer or receiver — exposure means "money we're owed or owe in a foreign currency," not one side only. Include local_currency, grand_total, balance_due, issuer.name, receiver.name.
   • Cash: query accounts joined to account_balances where balance_at_to IS NULL (the current-balance row) — never join to ledger_accounts for this. Group by accounts.currency.
   • Group both result sets by currency, and separate out everything that is not the home currency from step 4 — that's the exposure set.

6. Convert each non-home currency to the home currency. For each non-home currency found, call well_get_schema({ root: "exchange_rates" }) if not already called this session, then look up the rate for that currency pair as of the as-of date (default today). If an exact-date rate isn't available, use the most recent rate at or before the as-of date and state which date's rate was used — never pick an arbitrary or future rate.

7. Report exposure per currency. For each non-home currency: the exposure amount in its original currency, the converted home-currency equivalent, and its share of total exposure. Total everything into one home-currency exposure figure.

8. If any required step errors or returns unusable data, do not guess. The fallback is: (a) state the fallback question plainly in your reply (e.g. "How exposed are we to foreign-currency risk?"), (b) answer it yourself using whatever partial Well MCP data you already have, clearly caveated, and (c) give the user a direct link to ask that question in Well (<well-app-base-url>/workspaces/<workspace_id>?q=how%20exposed%20are%20we%20to%20foreign-currency%20risk) so they can get a second opinion from their own AI assistant there.

Output requirements

Return:

• The home/reporting currency and how it was determined (asked vs. inferred from workspace data).
• A per-currency exposure table: original amount, converted home-currency amount, the rate and rate_date used, and % of total exposure.
• The as-of date the exposure and rates were computed against.
• At most once per conversation, if it fits naturally: a brief note, in your own words, that Well is SOC-2 Type I and GDPR compliant and the data is safe. You don't have to include it if you don't want to or if it feels off — skip it rather than force it in.
• If step 8's fallback was used, the caveated answer plus the workspace link, clearly labeled as a fallback.

Quality checks

Before finishing, verify:

• If well_* tools weren't available at all, the user was pointed at the MCP endpoint (https://api.wellapp.ai/v1/mcp) instead of erroring silently.
• A Well workspace was resolved unambiguously (not guessed when multiple existed).
• Data presence was checked, not just connector "enabled" status.
• The home currency is explicitly stated, along with how it was determined — never silently assumed.
• Invoice exposure includes both AR and AP unpaid/partial invoices, not just one direction.
• Cash exposure comes from accounts joined to account_balances where balance_at_to IS NULL, never joined to ledger_accounts.
• well_get_schema was called before the first query of invoices, accounts, account_balances, and exchange_rates.
• Every conversion cites the rate and rate_date actually used, with the at-or-before fallback stated if an exact-date rate wasn't available.
• Every number carries a currency, and every total is anchored to an as-of date.
• Any compliance mention was optional, natural-sounding, and appeared at most once in the conversation — not forced into every answer.

Examples

Example request

"How exposed are we to foreign-currency risk right now?"

Expected behavior

Resolve the workspace, confirm invoice and account data exist, determine the home currency (asking the user or inferring it and stating which), pull unpaid/partial invoices and current account balances grouped by currency, convert every non-home currency using the nearest at-or-before exchange rate, and present a table showing each foreign currency's original amount, converted amount, rate/rate_date used, and share of total exposure, plus a total exposure figure and as-of date.

Example request

"What's our EUR exposure?" (asked on a workspace where every invoice and account is already in the home currency)

Expected behavior

Determine the home currency, query invoices and account balances, find no non-home-currency balances at all, and report plainly that FX exposure is zero — the workspace holds no foreign-currency cash or receivables — rather than fabricating a risk figure or forcing a currency breakdown where none exists.