Tool System

Overview

Wilson’s tools are LangChain DynamicStructuredTool instances with Zod schemas for input validation. The tool registry collects all tools and conditionally loads them based on available API keys and configuration.

Built-in Tools

Tool	Description	Always Available
csv_import	Import transactions from CSV, OFX, or QIF files	Yes
categorize	AI-powered transaction categorization	Yes
transaction_search	Search and filter transactions by any criteria	Yes
spending_summary	Generate spending breakdowns by category, merchant, or period	Yes
anomaly_detect	Find duplicates, unusual amounts, forgotten subscriptions	Yes
export_transactions	Export filtered transactions to CSV or XLSX	Yes
web_search	Search the web for merchant info or financial questions	Requires API key

Tool Registry

The registry (src/tools/registry.ts) manages tool discovery and loading:

1. Collects all built-in tools
2. Conditionally includes tools based on environment variables (e.g., web search requires an API key)
3. Loads MCP tools from configured servers
4. Provides rich description strings injected into the system prompt

Each tool has two levels of description:

• Zod schema description — Used by the LLM to understand parameters
• Rich description string — Injected into the system prompt for better tool selection

Tool Architecture

import { DynamicStructuredTool } from '@langchain/core/tools';
import { z } from 'zod';

const myTool = new DynamicStructuredTool({
  name: 'my_tool',
  description: 'What this tool does',
  schema: z.object({
    query: z.string().describe('Search query'),
    limit: z.number().optional().describe('Max results'),
  }),
  func: async ({ query, limit }) => {
    // Tool implementation
    return JSON.stringify(results);
  },
});

Import Parsers

The import system includes bank-specific CSV parsers:

Parser	File	Bank Format
Chase	parsers/chase.ts	Chase CSV with Details, Posting Date
Amex	parsers/amex.ts	American Express CSV
Bank of America	parsers/bofa.ts	BofA checking and credit card formats
Generic	parsers/generic.ts	Fallback for any CSV with date/amount columns
OFX	parsers/ofx.ts	OFX v1.x (SGML) and v2.x (XML)
QIF	parsers/qif.ts	Quicken Interchange Format

All parsers return a ParsedTransaction interface that normalizes the data before database insertion.

Format Detection

detect-bank.ts sniffs file format in this order:

1. OFX — Checks for <OFX> or OFXHEADER markers
2. QIF — Checks for !Type: header
3. CSV — Sniffs column headers to identify bank format

Web Search Providers

Wilson supports multiple web search providers for merchant research:

Provider	API Key
Exa	EXA_API_KEY
Perplexity	PERPLEXITY_API_KEY
Tavily	TAVILY_API_KEY
Brave	BRAVE_API_KEY

Only one is needed. Wilson uses whichever key is available.