financial-insights

Financial insights

Use this skill for read-only questions about the user's Link financial data. Call the extension's native tools with their discovered mount prefix, such as link__list_transactions. Inputs and results are structured objects; use the tool schemas for parameter names and constraints.

For purchases or payment credentials, load the mounted create-payment-credential skill instead.

Authentication and access

The application configures the wallet and authorization provider. If Eve asks the user to connect Link, let that authorization finish before continuing. Do not ask for tokens in chat. If access is denied or a tool reports missing permissions, explain what data could not be retrieved and stop. Do not repeatedly retry the same denied operation.

Choose the right tools

Use the smallest set that answers the question.

For restaurant spending last month, retrieve transactions for that period. For an account balance, retrieve balances. For connected accounts, retrieve sources. Combine tools only when the question requires it, such as joining source names to balances.

Amounts and sources

Financial-data amounts are integers in the currency's smallest unit. Format using the currency's ISO 4217 minor-unit exponent; do not always divide by 100. For example, 152340 represents $1,523.40 USD.

Only transaction amount uses negative values for money leaving the account and positive values for money entering. Interpret balance fields according to their balance type. Keep currencies separate when aggregating.

A source is an account connected to Link. Use its id to join records exposing source_id. Do not guess which account owns a transaction whose source_id is null. Sources can describe banks, cards, and other account types.

Transactions

Call list_transactions with the relevant filters, for example:

{
  "start_date": "2025-01-01",
  "end_date": "2025-01-31",
  "category": "groceries",
  "origin": "external_connection",
  "sources": ["<source_id>"],
  "limit": 100
}

Choose dates and filters from the user's question; omit unnecessary fields.

Useful response fields:

Distinguish spending from credits, deposits, and refunds. Explain whether a reported total is gross spending or net movement. Group by merchant, category, source, currency, or period only when relevant. Label summaries based on a limited window or partial pagination accordingly.

Balances

Call list_balances with {} for an initial page, or filter by sources:

{ "sources": ["<source_id>"], "limit": 100 }

Use current for a general balance question and cash.available when the user asks about available cash. Do not present credit used as available funds. Preserve currencies, summarize by source, and mention relevant freshness limits.

Sources

Call list_sources with {} or pagination arguments.

Use capabilities and granted actions to understand what data is accessible. Summarize institution, account type, and connection status when relevant. Avoid exposing full account numbers, tokens, or unnecessary identifiers.

Insights

Insights are signals Link computes ahead of time, such as top_brand_by_transaction_count_per_category_t180d (top brands per shopping category over the last 180 days, by transaction count). New types can appear without an extension release.

1. If you do not already know the applicable insight ID or its access requirement, call list_available_insight_types with {}. Each type has an id, a description, and, when the current grant needs more access, an authorization_remediation with the scope or authorization_details required.
2. Call list_insights with only the IDs the task needs, for example { "insights": ["top_brand_by_transaction_count_per_category_t180d"] }. Omit insights only when the user asks for an overview of all insights.

Both tools accept limit (1 to 100, default 10) and starting_after (the last returned insight id); they do not accept ending_before.

Handle each result by status and error_code:

Never report missing permissions, pending, or failed results as zero activity.

For missing_permissions, tell the user which access is missing (for example, transaction access for a Link payment detail) and why. Access comes from the application's authorization provider, never from chat. If Eve presents an authorization challenge, let the user complete it, then call list_insights once more for the same IDs. If authorization is declined or access is still missing, continue without the insight and say so. Request nothing beyond the supplied remediation.

Values are tagged by type. number_of_items values carry number_of_items.label, naming what was counted (such as the brand), and number_of_items.count; the entry label names the category, for example "Top brand from Clothing and accessories shopping category" with J.crew and a count of 10. The number_of_items.label may be absent. For an unfamiliar type, describe only what its fields make clear, or omit it.

Insights describe observed history. Explicit user instructions and stated preferences always override them. Describe a pattern as observed, for example "your recent transactions point to J.crew for clothing", not as a preference the user declared. Results cover only authorized sources; mention that coverage may be incomplete.

Pagination

list_transactions, list_balances, and list_sources accept:

Responses contain data and may contain has_more. When has_more is true, derive starting_after from the last returned item:

For example, continue a transaction query with the same filters and starting_after: "<last_transaction_id>". Change only the cursor across pages. Stop when has_more is false or absent, or when the user's non-exhaustive lookup is satisfied. If more results are reported but the page is empty or lacks a usable cursor, stop and explain that pagination could not continue.

Fully paginate when a complete bounded result is needed, such as a total for a specified month. Do not present a partial page's sum as the complete total.

Answer the question

State the answer first, followed by the relevant period and source. Mention limitations such as missing categories, pending activity, stale balances, partial results, or inaccessible accounts. Summarize rather than dumping raw records or object IDs.

If the tools return no matching data, say that no data was available for the requested filters and access. That does not prove no activity occurred or that an inaccessible balance is zero. Report uncertain derived insights as uncertain. Mention as_of when stale data could change the answer.

This skill does not move money, initiate payments, or modify sources. Retrieve only relevant financial data and never expose payment credentials.