Skip to main content
Glama
fde-week3-agent

fde-week3-agent

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.

Related MCP server: mcp-chinookdb-server

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

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

Create .env:

ANTHROPIC_API_KEY=sk-ant-...

Download Chinook:

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

Usage

Raw function calling agent:

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):

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

Test the MCP server standalone with the MCP inspector:

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

Available Tools

4 tools
describe_tableA
Read-onlyIdempotent

Return the column schema for a table.

Call this before writing any SQL that references a table you haven't described yet. You can call it in parallel for multiple tables in one turn. Returns an error if the table name doesn't exist — use list_tables to see valid names.

Args: name: The exact table name, case-sensitive, as returned by list_tables.

Inputs: name (required).

list_tablesA
Read-onlyIdempotent

List all tables in the connected Chinook database.

Call this FIRST when you don't yet know what data is available. Returns a JSON object with a 'tables' key holding a list of table names. Each name can then be passed to describe_table to learn the columns. Cheap to call; use it freely rather than guessing table names.

Inputs: no named parameters.

query_sqlA
Read-onlyIdempotent

Execute a single SELECT statement against the database and return results.

This tool is READ-ONLY: INSERT, UPDATE, DELETE, DROP, and any other non-SELECT statement will be rejected. Multiple statements chained with semicolons will also be rejected — send one SELECT at a time.

Returns an object with: columns (list of column names), row_count, rows (list of row objects), and truncated (true if there were more than 100 rows, in which case only the first 100 are returned).

If you don't know the schema, call list_tables and describe_table FIRST. Never invent column or table names — verify them by describing the tables involved.

Args: sql: A single, valid SQLite SELECT statement. Use standard SQL. You may include JOIN, WHERE, GROUP BY, ORDER BY, LIMIT, and aggregate functions. Do not include a trailing semicolon.

Inputs: sql (required).

summarize_resultsA
Read-only

Produce a natural-language summary of query results.

Use this ONLY when the rows need narrative interpretation (multiple rows, aggregate patterns, comparisons across groups). For single-row lookups or trivially small results, answer directly in your response text without calling this tool.

Args: rows: The 'rows' list returned from query_sql. question: The user's original question, verbatim.

Inputs: rows (required), question (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.7/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a distinct, non-overlapping purpose: listing tables, describing schema, executing SQL queries, and summarizing results. No two tools could be confused for the same task.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern in snake_case (list_tables, describe_table, query_sql, summarize_results), making the set predictable and easy to use.

    Tool Count5/5

    4 tools perfectly cover the essential workflow for a read-only database agent: discover tables, inspect schema, run queries, and summarize results. Each tool earns its place with no unnecessary additions.

    Completeness4/5

    The set covers the core workflow well, but lacks a tool for quickly previewing sample data or obtaining table statistics, which would require writing a query manually. Minor gap, but functional.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables AI agents to interact with SQLite databases by querying schemas, executing SQL, and inspecting table metadata. It supports safe database access through configurable read-only modes, query timeouts, and dry-run execution plans.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A read-only MCP server that enables LLMs to safely explore and query any SQLite database via natural language. It exposes tools for listing tables, describing schemas, and executing SELECT/WITH queries with built-in safety guards like write prevention and row limits.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP tool server providing SQLite database access for AI agents.
      MIT