sql-analyst
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| SQL_ANALYST_DB | No | Path to a `.duckdb` or `.sqlite` database file to use instead of the default Olist database. | |
| SQL_ANALYST_LLM | No | LLM backend to use. Set to `anthropic` to use Claude instead of Ollama; this also requires SQL_ANALYST_ALLOW_PAID and ANTHROPIC_API_KEY. | ollama |
| SQL_ANALYST_DOCS | No | Path to a schema-docs YAML file in the format of `src/sql_analyst/db/schema_docs.yaml`. | |
| ANTHROPIC_API_KEY | No | Anthropic API key. Required when SQL_ANALYST_LLM=anthropic. | |
| SQL_ANALYST_MODEL | No | Model name for the local LLM. Any model that can return JSON works. | |
| SQL_ANALYST_ALLOW_PAID | No | Set to `1` to allow paid LLM calls when SQL_ANALYST_LLM=anthropic. | |
| SQL_ANALYST_BUDGET_USD | No | Spending cap in USD for paid calls. The process stops before it goes over the cap. Default is $1. | 1 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Read-only access to an analytics database (by default Olist, a Brazilian e-commerce marketplace, 2016-2018: orders, items, payments, reviews, customers, sellers, products). Questions may be in English or Arabic. To write SQL yourself: list_tables, then describe_table for the tables you need, then run_sql. Read schema://definitions first: business terms such as revenue have fixed meanings here. To let this server's agent do it: ask_data (slower; it writes, checks, fixes and explains the query). Only single SELECT queries run; anything else is refused with the reason.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| list_tablesA | List the tables in the database with a one-line description and column count. |
| describe_tableA | Columns of one table: type, meaning (when documented) and a few common values, which show how values are spelled (e.g. 'delivered', 'SP'). |
| run_sqlA | Run one read-only SQL query and return its rows. The query is parsed and checked first: only SELECT on this database's tables, no functions that read files, URLs or settings. A refused or failed query returns the reason, so you can fix it. |
| ask_dataA | Answer a business question with this server's agent: it writes the SQL, checks it, runs it, fixes it if it fails, and explains the result in the question's language. Returns the answer, the SQL that ran, up to 200 rows, a chart spec and (optionally) a PNG chart. Takes 5-30 seconds. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| analyse | Answer a business question with SQL you write and check yourself. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| schema_overview | The whole schema as the agent sees it: tables, columns, joins and definitions. |
| definitions | How business terms are computed here (revenue, GMV, late delivery, ...). |
TDQS
Scored across 4 tools
list_tables and describe_table are clearly separated (breadth vs. column detail), and run_sql vs. ask_data differ by input type (raw SQL vs. natural-language question). The one soft overlap is that ask_data also ends up running SQL, so an agent may over-rely on it and skip run_sql, but the descriptions make the intended split explicit.
All four names follow a verb_noun snake_case pattern: list_tables, describe_table, run_sql, ask_data. The verbs are distinct and descriptive, with no mixed conventions or casing.
Four tools is lean but each has a distinct role: discovery (list/describe), direct execution (run_sql), and delegated analysis (ask_data). Nothing looks redundant or padded for a read-only SQL analyst server.
Schema discovery plus query execution plus a natural-language fallback covers the core read-only analytics lifecycle with no dead ends. Minor gaps exist: no way to search across schema objects or preview sample rows outside describe_table's few values, and no explain/plan tool for debugging slow queries.