AI-agent skill · Claude Code · Codex · Cursor · Gemini CLI

Is your SQL answer right?

Trusted SQL Analyst turns plain-English questions into SQL, then double-checks the answer like a careful senior analyst. It maps the database first, keeps a glossary of what columns and business terms mean, runs 25 automatic checks for silent mistakes, proves the number with a second query written a different way, and explains the result in plain English with its assumptions. Read-only and local: SQLite, DuckDB, CSV/Parquet/Excel folders, Postgres and MySQL.

Get it on Agensi · $9.99 ↗See the demoBlind test resultsGitHub ↗

The query ran fine. The number was 9× too high.

"Revenue by genre" on the Chinook music-store database. Summing the invoice total after joining to invoice lines repeats every invoice once per line - a classic AI-written SQL mistake that returns a confident number.

Rock revenue, plausible-looking SQL7,720.02

The check: FAIL - "each Invoice row appears 5.44 times on average after the joins (2,240 joined rows for 412 invoices)".

Rock revenue, corrected826.65

Summed from invoice lines at their own grain. Check: PASS; the 24 genres add up to the true total 2,328.60; a second query by another route agrees.

The raw check output for the wrong query:

## SQL check: FAIL ❌

Rows returned: **24** · dialect sqlite · sqlanalyst 1.1.0

| # | severity | rule | problem |
|---|---|---|---|
| 1 | high | TSQ105 Join multiplies rows before SUM/AVG/COUNT (fan-out) | After the joins, each `Invoice` row appears 5.44 times on average (2,240 joined rows for 412 Invoice rows). SUM(i.total) therefore adds up the same `Invoice` rows several times. |

**Fixes**
1. Aggregate `Invoice` at its own grain before joining (subquery/CTE), or use COUNT(DISTINCT key); never SUM/AVG a parent-table column after joining to its child rows.

**Verified**
- Reconciled (internal consistency): the 24 group totals of `revenue` add up to the ungrouped total of the same rows, 20,848.62. This does not prove the rows themselves are right.

**Result preview**

| Name | revenue |
|---|---|
| Rock | 7,720.02 |
| Latin | 3,472.55 |
| Metal | 2,093.13 |
| Alternative & Punk | 1,961.66 |
| TV Shows | 817.71 |
| Jazz | 746.46 |
| Drama | 544.61 |
| Blues | 429.66 |
| R&B/Soul | 338.62 |
| Reggae | 332.64 |
| Classical | 317.04 |
| Soundtrack | 242.55 |
| Pop | 239.75 |
| Alternative | 211.17 |
| Sci Fi & Fantasy | 198.87 |
| World | 182.18 |
| Hip Hop/Rap | 166.41 |
| Heavy Metal | 161.37 |
| Electronica/Dance | 149.62 |
| Easy Listening | 138.6 |

Tested honestly

A separate AI agent that had never seen the tool wrote 24 new realistic wrong queries (with the correct query for each) on three real databases. The checker was frozen and run once.

14 / 16SQL-mechanics mistakes caught in the blind test (joins, NULLs, dates, text, grouping, division)
0 / 8business-meaning mistakes (wrong column or definition) - not detectable from SQL; the skill handles these with the glossary and the second-query step
2 / 24correct queries that got a REVIEW note
31 / 32wrong queries flagged in the 32 development cases (0 correct queries flagged)
All 24 blind cases
CaseTypeMistake (written by the test agent)Result
B01sql-mechanicsSums the invoice-level Total after joining to invoice lines, so each invoice total is counted once per line (join fan-out) and attributed to every genre on the invoice.✅ caught
B02sql-mechanicsNOT IN against a subquery that contains a NULL (the General Manager's ReportsTo) is never true, so the count is 0.✅ caught
B03sql-mechanicsAll operands are integers, so the division truncates and the percentage loses its decimals (6.0 instead of 6.11).✅ caught
B04sql-mechanicsCOUNT(*) after a LEFT JOIN counts the NULL-padded row, so artists with no albums are counted as having 1 album.✅ caught
B05business-meaningSums catalog list prices of all Jazz tracks (the value of the catalog) instead of what was actually sold on invoice lines.— missed
B06sql-mechanicsState <> 'CA' evaluates to NULL for customers with no state, silently dropping 29 customers.✅ caught
B07business-meaningAverages individual invoice totals (average order value) rather than each customer's summed lifetime spend.— missed
B08sql-mechanicsJoins Customer to Employee on CustomerId = EmployeeId instead of SupportRepId, pairing each employee with an unrelated customer.— missed
B09sql-mechanicsOrderDate includes a time of day, so BETWEEN ... '2021-12-31' excludes orders placed later on December 31.✅ caught
B10business-meaningUses the product's current list price (Products.UnitPrice) instead of the price actually charged on each order line.— missed
B11sql-mechanicsAND binds tighter than OR, so the freight filter only applies to United Package and every Speedy Express order is counted.✅ caught
B12sql-mechanicsExact string match misses a supplier whose Country is stored as 'Sweden ' with a trailing space.✅ caught
B13business-meaningGroups by the shipping destination country on the order rather than the customer's own country, which differ for most orders.— missed
B14sql-mechanicsThe self-join roles are swapped: it groups by the subordinate (m) instead of the manager (e), so every employee shows 1 report.— missed
B15sql-mechanicsOrder-level Freight is summed once per matching beverage line, so orders with several beverage products have their freight counted multiple times.✅ caught
B16business-meaningCompares only units in stock to the reorder level and ignores units already on order, so products that are being replenished are flagged.— missed
B17sql-mechanicsGroups by actor name instead of actor_id, merging the two different actors named SUSAN DAVIS into one person with 54 films.✅ caught
B18sql-mechanicsFiltering the right-hand table in WHERE turns the LEFT JOIN into an inner join, so customers with zero rentals are dropped from the average.✅ caught
B19sql-mechanicsCounts rental rows instead of distinct films (missing DISTINCT), so a film rented many times is counted many times.✅ caught
B20sql-mechanicsCOUNT(*) on the LEFT JOIN counts the NULL row, so the 42 films with no inventory are counted as having one copy.✅ caught
B21sql-mechanicspayment_date is a timestamp, so BETWEEN ... '2005-07-31' drops every payment made during July 31.✅ caught
B22business-meaningAttributes payments to the store of the staff member who took the payment, not the store that owns the rented inventory.— missed
B23business-meaningCounts the films in each category (catalog size) instead of the number of rentals.— missed
B24business-meaningRanks customers by number of payments instead of the sum of amounts paid.— missed

With and without the skill: two fresh agents answered the same 12 business questions; both got 12 / 12. A strong model working carefully does not need the skill to be accurate on questions like these - the measured value is catching mistakes before you trust a number, and answers that state their assumptions and checks. Databases: Chinook, Northwind (609,283 order lines) and Sakila.

What it checks

Joins

Fan-out double counting (SUM/AVG/COUNT after a one-to-many join, with the measured factor) · rows dropped by INNER JOIN · join without a condition · LEFT JOIN undone by WHERE · COUNT(*) after LEFT JOIN

NULLs

NOT IN with a NULL in the subquery · = NULL · negative filters (<>, NOT LIKE) that drop NULL rows · AVG skipping NULLs

Text & values

'usa' vs 'USA' vs 'USA ' · values that do not exist (closest matches shown) · LIKE that also matches other categories · list columns ('a,b,c') matched with =

Dates

BETWEEN / <= that drops the last day when values have a time · = on a timestamp · dates stored as non-ISO text

Grouping & maths

Columns neither grouped nor aggregated · grouping by a name that merges different people · integer division · AND/OR without brackets · LIMIT without ORDER BY

Result checks

Empty result: which filter emptied it · duplicate groups · groups that do not add up · NULL groups · impossible percentages

How your agent uses it

  1. Maps the database once: tables, keys, measured joins (orphans, NULL keys, one-to-many), messy values, how dates are stored.
  2. Pins down the question with a glossary: metric definition, grain, time window, what "active" or "revenue" means here.
  3. Writes the SQL with the trap list in mind.
  4. Runs the checks on the query and its real result - with numbers, not guesses.
  5. Proves the number with a second query by a different route and compares them.
  6. Answers in plain English: the number, how it was calculated, the assumptions, the checks done, and the SQL.

Good to know

Read-only

Refuses INSERT/UPDATE/DELETE/DDL, file-reading functions and multiple statements; every query has a timeout.

Review other SQL

Paste a query from a colleague or another AI: you get the problems, the measured impact and a fixed query.

Small install

pip install sqlglot (+ duckdb for files, SQLAlchemy for servers). Tested on SQLite and DuckDB.

Honest limits

It cannot know your business meaning; a PASS is never proof the question was understood. That is why the glossary and the second query exist.

Get it on Agensi · $9.99 ↗GitHub ↗

Made by Muhammad Shahmeer · Data Science MSc, University of Naples Federico II · © 2026, all rights reserved.