Finance Agent

A LangGraph agent that routes natural-language stock questions between a custom MCP server (yfinance quant tools) and a news tool, validated by a hand-rolled eval set.

Built to close two skill gaps: designing MCP servers (tool surface, descriptions-as-routing-logic) and agent orchestration with routing judgment.

---

Architecture

User Query
    │
    ▼
┌─────────┐
│  route  │  3-way classifier: quant / news / both
└────┬────┘
     │
     ├──────────────────────┬─────────────────────
     ▼                      ▼
┌─────────┐           ┌──────────┐
│  quant  │           │   news   │
│ (ReAct) │           │  (ReAct) │
└────┬────┘           └────┬─────┘
     │                     │
     └──────────┬───────────┘
                │
        ┌───────┴────────┐
        │                │
        ▼                ▼
┌──────────────┐   ┌───────────┐
│finish_single │   │ synthesize│
│   _source    │   │           │
└──────┬───────┘   └─────┬─────┘
       │                 │
       └────────┬─────────┘
                ▼
             Answer

Nodes:

• route — classifies the query; no tool calls, just a decision
• quant — ReAct agent with 5 MCP tools; picks the right tool(s) for the question
• news — ReAct agent with get_recent_news; handles news/context questions
• finish_single_source — pass-through for single-path queries; promotes result to answer
• synthesize — reconciles quant + news outputs into one coherent answer for "both" queries

For "both" queries, quant and news run concurrently; LangGraph holds until both complete before running synthesize.

---

MCP Server — Quant Tools

Five tools, each scoped to a single question shape:

Tool	Use case
get_stock_price(ticker, date?)	Point-in-time price lookup
get_fundamentals(ticker)	P/E, EPS, market cap, revenue growth, margins
compare_metric(tickers[], metric)	Side-by-side fundamentals comparison across companies
get_price_history_stats(ticker, period)	Return, volatility, vs-average over a lookback period
get_earnings_date(ticker)	Next/most recent earnings date

Tool descriptions include explicit negative cases ("not for X, which belongs to tool Y") — required because several tools share similar parameter shapes and would otherwise be ambiguous to the router.

---

Setup

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env  # add your ANTHROPIC_API_KEY

---

Usage

python -m agent.graph "What's Tesla's P/E ratio?"
python -m agent.graph "Why did NVDA drop this week?"
python -m agent.graph "Has AMZN's stock kept pace with its revenue growth?"

---

Evals

pytest evals/test_agent.py -v

18 queries across four categories: quant, news, both, and adversarial. Adversarial cases include keyword traps (news language wrapping quant questions) and false-premise queries (assertions about price movement that must be verified before explaining).

Result: 15/18 → 18/18 after correcting two brittle ticker-string assertions and adding a false-premise classification rule to the router prompt.

---

Key Design Decisions

1. Tool descriptions as routing logic. Every tool description explicitly states what it does not handle. Without negative cases, tools with overlapping parameter shapes (e.g. get_stock_price and get_price_history_stats both take ticker + date-ish params) are ambiguous to the LLM router.

2. News as a plain LangGraph tool, not a second MCP server. The instinct was "second MCP server = reusable building block." Pushed on it: reusable for what? No concrete second consumer existed. A second MCP server means a second subprocess to launch and manage; a plain @tool is a single in-process function. The process-boundary overhead had no matching benefit.

3. Router classifies intent, agents pick tools. The router does 3-way classification only — it does not pick which quant tool to call. LLM tool-selection (matching a query to one of 5 tool descriptions) is flexible/non-deterministic work that belongs inside the quant ReAct loop, not duplicated into the router prompt.

4. Synthesis must reconcile, not concatenate. The synthesis prompt explicitly instructs the model to connect quant data and news context into a single coherent answer. "Do not just list both separately — connect them." Without this, the "both" path produces two paragraphs stapled together rather than an actual answer.