List user tables in shop.db with a one-line purpose for each.

Use this first to discover the real schema. Internal SQLite tables such as sqlite_sequence are omitted. Does not invent columns (customers has no country). Returns {tables: [{name, purpose}, ...]}.

Describe columns, types, primary keys, and foreign keys for one table.

Use before writing joins. Returns actual SQLite metadata only — never fabricates fields such as country. Parameters: table (name from list_tables). Returns {table, columns: [{name, type, primary_key, ...}], foreign_keys}.

Run a single read-only SQL statement against shop.db.

Allowed: one SELECT, WITH (CTE), or EXPLAIN. Writes and DDL (INSERT, UPDATE, DELETE, REPLACE, DROP, ALTER, CREATE, TRUNCATE, ATTACH, VACUUM, REINDEX, PRAGMA) are rejected with an explicit not-allowed error. Stacked statements (semicolons) are rejected. Prefer shop_analytics for rankings and yearly revenue.

Pagination: default limit 100, maximum 1000 (error if exceeded), offset default 0. Returns {columns, rows, truncated, row_count, next_offset} or {error, sqlite_error?}. The database is opened read-only; refused mutations leave the file unchanged.

Shop aggregations without hand-written SQL.

Operations: top_customers_by_spend (name, email, total_amount; default limit 5), customer_most_orders (name, email, order_count), top_products (product_name, units_sold, revenue; default limit 5), top_categories (category, revenue; default limit 3), revenue_by_year (requires year). Spend/units/revenue use quantity * unit_price and exclude cancelled orders. Year is taken from order_date.