# fde-week3-agent

A natural-language SQL agent that queries the Chinook sample database, built two ways: with raw function calling, then refactored to use the Model Context Protocol (MCP).

Built as week 3 of a 16-week forward-deployed engineering study plan. The goal: internalize the agent loop, understand why tool descriptions matter more than tool code, and see what MCP actually adds (and doesn't add) over raw function calling.

## What it does

Answers natural-language questions like "which country has the most customers?" or "what are the top 5 best-selling artists by total revenue?" against a real SQLite database. The agent doesn't hardcode any SQL — it discovers the schema, writes queries, and interprets results dynamically.

Two working implementations of the same agent:

- **Raw function calling** (`main.py`): tools are Python functions in `tools.py`, schemas are hardcoded in `tool_schemas.py`, dispatched via a lookup dict in `agent.py`.
- **MCP** (`main_mcp.py`): the same tools are exposed by an MCP server (`mcp_server.py`) and consumed by a client agent (`mcp_client_agent.py`). Tool schemas are fetched dynamically at startup, not hardcoded.

## Why both

The agent's behavior is identical across both implementations — same queries, same answers, same latency profile. That equivalence is the point. It demonstrates that MCP is a *delivery mechanism* for tools, not a change to how agents reason. Which one to pick is an organizational decision:

- Raw is right when the agent and tools ship together and you don't need cross-agent reuse
- MCP is right when tools are maintained separately, when the customer might swap agents later, or when the same tools need to serve multiple agents

## The four tools

- `list_tables` — discoverability. Returns table names.
- `describe_table(name)` — discoverability. Returns column schema for a given table.
- `query_sql(sql)` — read-only SELECT execution. Rejects INSERT, UPDATE, DELETE, DROP, and multi-statement input at the tool level (not just in the description).
- `summarize_results(rows, question)` — pure-LLM tool that generates natural-language summaries of query results.

## Security model

The read-only constraint on `query_sql` is enforced in the tool's Python code, before the SQL reaches the database. The description tells the model the rule; the code enforces it. This is defense in depth: even if the model is confused, prompt-injected, or from a weaker model that ignores instructions, the destructive operation never reaches the database.

Same enforcement lives in the tool code whether accessed via raw dispatch or MCP. Refactoring to MCP doesn't move the security boundary — the boundary is in `tools.py`, which is unchanged across implementations.

## Setup

```bash
git clone https://github.com/jordanmatusik24/fde-week3-agent
cd fde-week3-agent
uv sync
```

Create `.env`:

```
ANTHROPIC_API_KEY=sk-ant-...
```

Download Chinook:

```powershell
Invoke-WebRequest -Uri "https://github.com/lerocha/chinook-database/raw/master/ChinookDatabase/DataSources/Chinook_Sqlite.sqlite" -OutFile "chinook.db"
```

## Usage

Raw function calling agent:

```bash
uv run python main.py "How many customers are in the database?"
uv run python main.py "What are the top 5 best-selling artists by total revenue?"
uv run python main.py "Are there any customers who haven't made a purchase?"
```

MCP agent (same questions, tools served over MCP protocol):

```bash
uv run python main_mcp.py "How many customers are in the database?"
```

Test the MCP server standalone with the MCP inspector:

```bash
uv run mcp dev mcp_server.py
```

## Architecture

**Raw:**
```
main.py → agent.py (dispatch loop) → tools.py (implementations)
                                   ↑
                              tool_schemas.py (hardcoded)
```

**MCP:**
```
main_mcp.py → mcp_client_agent.py → MCP protocol over stdio → mcp_server.py → tools.py
                                                                    ↑
                                                       schemas generated from decorators
```

## Findings

- **Description quality dominates tool code quality.** A tool with a perfect implementation and a vague description gets misused. A tool with a middling implementation and a sharp description gets called correctly. The description is the model's API contract.
- **Discoverability tools prevent schema hallucination.** Without `list_tables` and `describe_table`, an agent asked to query an unknown database invents plausible-looking but wrong SQL based on training-data conventions. With them, the agent observes the schema before writing SQL, and correctness follows.
- **Parallel tool calls happen when the description hints at them.** The `describe_table` description ends with "you can call it in parallel for multiple tables in one turn." The model then bundles 3-4 describes into a single turn on multi-table queries, cutting latency 2-3× vs sequential discovery.
- **Constraints enforced only in prompt/description are voluntary. Constraints in tool code are mandatory.** The SELECT-only check has to live in `tools.py`, not just in the description, because the description is documentation and code is the wall. This distinction is the answer to every customer security review question about what an agent can and cannot do.
- **MCP doesn't change agent behavior.** Same queries, same answers, same latency profile across the two implementations. MCP shifts *where tools are maintained*, not *how agents reason*.

## Stack

- Python 3.12, managed by [uv](https://docs.astral.sh/uv/)
- [Anthropic SDK](https://github.com/anthropics/anthropic-sdk-python) for Claude Sonnet 4.5
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) for the MCP server and client
- [typer](https://typer.tiangolo.com/) for the CLI
- [Chinook sample database](https://github.com/lerocha/chinook-database) — a fictional digital music store schema