Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/astrxnomo/financial-analytics-agent/llms.txt

Use this file to discover all available pages before exploring further.

Every analytics capability in the Financial Analytics Agent follows a strict 1:1:1 pattern: one tool (agent/tools/<name>.ts) paired with one REST route (app/api/finance/<name-kebab>/route.ts) and one chart component (app/_components/tool-result/<name>.tsx). All three call agent/lib/finance.ts directly — the agent never crosses an HTTP boundary to reach its own data, so it works standalone under eve dev --no-ui with no Next.js process running. Types are defined once in agent/lib/finance.types.ts and shared across tools, routes, and chart components.

​
get_summary

Returns total income, total expense, and net for a date range (inclusive on both ends). Input: { from: string, to: string } — both dates in YYYY-MM-DD format. Return type: Summary 
interface Summary {
  from: string;
  to: string;
  income: number;
  expense: number;
  net: number;
}
Example question: “What were total revenues and expenses last year?” When to use vs. other tools: Use get_summary for whole-company financial totals over a date range. Do not use it for row counts or dataset metadata (use get_data_overview instead), and do not use it for per-department profit/margin breakdowns (use get_profitability).

​
get_trend

Returns a monthly time series of income or expense, optionally split by department. Input: 
{
  metric: "income" | "expense";
  groupBy: "month" | "department";   // default: "month"
  from: string;                       // YYYY-MM-DD
  to: string;                         // YYYY-MM-DD
  departments?: string[];             // exact names, e.g. ["Engineering", "Marketing"]
}
Return type: TrendPoint[] 
interface TrendPoint {
  period: string;
  department?: string;   // present only when groupBy is "department"
  value: number;
}
Example question: “How did marketing spend grow in Q2 vs Q1?” When to use vs. other tools: Use get_trend for “over time”, “growth”, “trend”, or “by department over time” questions. Use groupBy: "department" only when comparing across departments — defaulting to "month" keeps the chart uncluttered for single-series questions. Pass specific departments when the user names them so the chart doesn’t dilute the comparison with every other team. For the spend composition within a period (not the trend), use get_category_breakdown instead.

​
get_category_breakdown

Returns monthly per-category totals (spend mix or revenue mix over time). Input: 
{
  metric?: "income" | "expense";   // default: "expense"
  department?: string;              // exact department name, e.g. "Engineering"
  category?: string;                // exact category name, e.g. "Cloud Infrastructure"
  from: string;                     // YYYY-MM-DD
  to: string;                       // YYYY-MM-DD
}
Return type: { slices: CategorySlice[]; otherCategories: string[] } 
interface CategorySlice {
  period: string;
  category: string;
  value: number;
}
The tool ranks categories by their total across the requested range and returns otherCategories — the exact list of categories folded into the chart’s “Other” band. The CATEGORY_BREAKDOWN_TOP_N constant (currently 8) controls how many named categories appear before the rest are grouped. Example question: “Where does Engineering’s budget go each month?” When to use vs. other tools: Use get_category_breakdown for “what do we spend on”, “spend composition”, “breakdown by category”, or “where does the money go” questions. Pass category when the user asks about one specific category (e.g. “is the Cloud Infrastructure spike recurring”) to isolate that series rather than burying it in a multi-category chart. If the user asks what’s in the “Other” band, quote otherCategories directly from the tool result — do not re-derive it manually from the raw slices.

​
get_cashflow

Returns monthly income vs. expense with both the monthly net and the running cumulative net. Input: { from: string, to: string } — both dates in YYYY-MM-DD format. Return type: CashflowPoint[] 
interface CashflowPoint {
  period: string;
  income: number;
  expense: number;
  net: number;
  cumulativeNet: number;
}
Example question: “Are we burning cash or are we net-positive over the last year?” When to use vs. other tools: Use get_cashflow for “cash flow”, “burn rate”, “are we profitable over time”, and “net position” questions. The key distinction from get_summary is that cashflow is a time series — it shows how the balance evolved month by month, not just the endpoint totals. For profitability broken out by department (not over time), use get_profitability.

​
get_budget_status

Returns per-department budget vs. actual expense for one month only, with variance and percentage of budget used. Input: 
{
  month: string;         // any date in the target month, YYYY-MM-DD
  departments?: string[] // exact names; omit to include all departments
}
Return type: BudgetRow[] 
interface BudgetRow {
  department: string;
  budget: number;
  actual: number;
  variance: number;   // budget - actual (positive means under budget)
  pctUsed: number;    // actual / budget
}
Example question: “Which department went over budget this month?” When to use vs. other tools: Use get_budget_status for “over budget”, “budget status”, or “budget vs. actual” questions. There is no multi-month or annual budget aggregation — this tool covers exactly one month. If a question implies a longer window (“this year”, “over the last few months”), answer using the single latest closed month and say so explicitly (e.g. “for June 2026, the latest closed month”) rather than implying it covers the whole year.

​
get_anomalies

Returns expense transactions that exceed the statistical outlier threshold for their category within the requested date range. Input: 
{
  from: string;
  to: string;
  threshold?: number;      // std-dev multiplier, default 2.5; valid range 1–6
  departments?: string[];  // restrict returned list to these departments
  categories?: string[];   // restrict returned list to these categories
}
Return type: Anomaly[] 
interface Anomaly {
  id: number;
  date: string;
  amount: number;
  department: string;
  category: string;
  description: string;
  categoryMean: number;
  categoryStdDev: number;
}
The mean and standard deviation are computed from the full dataset, regardless of departments or categories filters. Only the returned list is narrowed — so the σ deviation labels on each anomaly are always calibrated against the same baseline. Example question: “Any unusual transactions this year?” When to use vs. other tools: Use get_anomalies for “unusual”, “anomaly”, “outlier”, or “suspicious spend” questions. Lower threshold toward 2 to surface more outliers for “any unusual spend” questions; raise it to 3 or higher for “only the most extreme outliers”. When the user names specific departments or categories, always pass them to narrow the list — returning every anomaly across the company when the user asked about one team is noise.

​
get_profitability

Returns income, expense, net, and margin per department for a date range, sorted most-profitable-first. Input: 
{
  from: string;
  to: string;
  departments?: string[];  // exact names; omit to include all departments
}
Return type: ProfitByDept[] 
interface ProfitByDept {
  department: string;
  income: number;
  expense: number;
  net: number;
  margin: number | null;   // net / income; null for cost-center departments
}
margin is null for departments that booked no income (Marketing, Operations, Finance). These are cost centers — a null margin means “not applicable”, not a data gap or a zero-margin break-even. Example question: “Which department is the most profitable and which is the biggest cost center?” When to use vs. other tools: Use get_profitability for “most/least profitable department”, “profit/margin by team”, or “net contributors vs. cost centers” questions. get_summary only totals the whole company. get_cashflow tracks profitability over time for the whole company, not across departments. This is the only tool that pairs a department’s revenue against its spend.

​
get_data_overview

Returns metadata about the dataset itself: row counts and date coverage. Input: none (no parameters). Return type: DataOverview 
interface DataOverview {
  dataFrom: string;
  dataTo: string;
  departments: number;
  categories: { total: number; revenue: number; expense: number };
  transactions: number;
  budgets: number;
}
Example question: “How many transactions do we have and what date range do they cover?” When to use vs. other tools: Use get_data_overview for questions about the data itself — record counts, coverage dates, how many departments or categories are tracked. Never use get_summary for these, since that returns financial totals (income/expense), not row counts.

​
Tool selection guide

Question typeCorrect tool
Trends, growth, over-time seriesget_trend
Over/under budget, budget vs. actualget_budget_status
Unusual, suspicious, or outlier spendget_anomalies
Whole-company totals (income, expense, net)get_summary
Spend or revenue mix by categoryget_category_breakdown
Cash flow, burn rate, cumulative net over timeget_cashflow
Profit, margin, net contribution by departmentget_profitability
Record counts, coverage dates, dataset metadataget_data_overview
getHighlights() is an internal library function with no corresponding agent tool. It powers the /api/finance/highlights REST endpoint, which is consumed by useFinanceHighlights in app/_components/agent-chat/use-finance-highlights.ts to generate the suggested question chips and inject live date ranges into the agent’s instructions each session. Because it runs before the user’s first message, it adds zero latency to the agent’s response path.

Build docs developers (and LLMs) love

Get started for freeTalk to us