List all configured database connections (id, name, type, limits).

Call this first to discover which databases exist and to get the name or id that every other tool's connection argument accepts. Read-only; returns an empty list when nothing is configured yet (add one with create_connection).

Register a new target database connection (credentials encrypted at rest).

Use once per database before introspecting or querying it. This only stores the connection — it does NOT verify connectivity or read the schema; follow with test_connection, then introspect_connection. Returns the created connection's id and metadata.

Check that a configured connection can be reached and authenticated.

Use after create_connection to validate credentials and network access before introspecting. Read-only: opens and closes a probe connection without reading the schema (use introspect_connection for that). Returns {success, message}.

Read the target database's structure (tables, columns, foreign keys) and cache it.

Run once per connection before querying, and again after the schema changes. Idempotent — re-running refreshes the cache. The cache is what list_tables, describe_table, and get_semantic_context read from. Returns counts of cached objects plus the number of embeddings generated.

Permanently delete a connection and all its cached schema + semantic metadata.

Removes the connection plus its glossary, metrics, dictionary, sample queries, and knowledge. Destructive and not reversible — use only to retire a database you no longer query. Returns {deleted: true}.

List a connection's cached tables, each with its columns.

Returns name, type, comment, row-count estimate, and per-column details (type, nullability, primary key). Reads the cache from introspect_connection (run that first if the result is empty). Use for a schema-wide overview; for one table's foreign keys and relationships, use describe_table. Read-only.

Describe one cached table in detail, including its foreign-key relationships.

Returns columns (with defaults/comments), outgoing foreign keys, and incoming references from other tables. Use when you need a single table's keys to write a join; for a list of all tables use list_tables. Reads the cache (introspect first). Raises if the table is not found.

Assemble grounded, SQL-ready context for a question.

Returns the relevant tables/columns, foreign keys, business glossary, metric definitions, value dictionaries, knowledge excerpts, and example queries as formatted text. This is the recommended first step of the lightweight path: take the result, write a read-only SELECT yourself, then call run_sql. Needs no LLM key. For a fully automated answer instead, use ask.

Execute a read-only SQL SELECT against the target database and return the rows.

Use to run SQL you wrote from get_semantic_context. Enforces read-only: rejects INSERT/UPDATE/DELETE/DDL and other unsafe statements; results are row-limited per the connection's max_rows. Returns columns, rows, row_count, truncated, and execution_time_ms. To have the server write the SQL for you, use generate_sql or ask.

Translate a natural-language question into SQL via the server LLM, without executing it.

Requires an LLM provider to be configured. Use when you want to review or edit the SQL before running it with run_sql. For zero-key operation, use get_semantic_context and write the SQL yourself; to also execute and interpret in one step, use ask. Returns the generated SQL plus supporting details.

Answer a natural-language question end-to-end via the server pipeline.

Builds context, generates SQL, validates, executes it (read-only), and interprets the results. This is the fully automated path and requires an LLM provider. Use it when you want a finished answer rather than raw rows; use the get_semantic_context + run_sql path for manual control, or generate_sql to get SQL without executing. Returns a Markdown report (summary, highlights, executed SQL, metadata, follow-ups, and a data preview).

List recent query executions for a connection, newest first.

Returns each execution's question, final SQL, status, row count, and timestamp. Use to review or reuse previously run queries. Read-only.

List the business glossary terms defined for a connection.

Returns each term, its plain-language definition, the SQL expression that implements it, and related tables. Glossary terms map business language (e.g. 'active customer') to SQL. Add with add_glossary_term; for numeric KPIs see list_metrics. Read-only.

Define a business glossary term that maps business language to a SQL expression.

Use to teach the semantic layer phrases like 'active customer' so future grounding and generation apply them consistently. For a named, reusable aggregate (a KPI) use add_metric instead. Returns the new term's id.

Delete one business glossary term by its id.

Destructive and not reversible. Look up ids with list_glossary. Returns {deleted} indicating whether a matching term was removed.

List the metric definitions for a connection.

Returns each metric's name, display name, SQL aggregate expression, and dimensions. Metrics are named, reusable KPIs. Add with add_metric; for phrase-to-SQL term mappings see list_glossary. Read-only.

Define a metric: a named, reusable SQL aggregate (a KPI).

Use for quantitative measures like revenue or default rate so grounding and generation can reuse them; for phrase-to-SQL mappings use add_glossary_term instead. Returns the new metric's id and name.

Delete one metric definition by its id.

Destructive and not reversible. Look up ids with list_metrics. Returns {deleted} indicating whether a matching metric was removed.

Map a coded column value to its business meaning (e.g. stage '1' -> 'Performing').

Use so grounding and generation can interpret enum-like codes. Requires the connection to be introspected first so the column can be resolved. Returns the new entry's id.

List saved example natural-language -> SQL pairs for a connection.

These validated pairs are used as few-shot examples that steer SQL generation. Add with add_sample_query. Read-only.

Save a validated natural-language -> SQL example to improve future generation.

Use to capture good question/SQL pairs for this connection; they are reused as few-shot examples by generate_sql and ask. Returns the new example's id.

List the knowledge documents imported for a connection.

Returns each document's title, source URL, and chunk count. Knowledge docs are searchable business context (policies, data dictionaries, runbooks) used during grounding. Add with add_knowledge or add_knowledge_url. Read-only.

Import a document you provide (plain text or HTML) as searchable business knowledge.

Use when you already have the content; to fetch it from a web page instead, use add_knowledge_url. The content is chunked and embedded for semantic retrieval during grounding. Returns the document id and chunk count.

Fetch a web page server-side and import its content as searchable business knowledge.

Use to ingest documentation by URL; to import content you already have, use add_knowledge. Performs an outbound HTTP GET (follows redirects, 30s timeout), then chunks and embeds the page. Returns the document id and chunk count.

Delete one knowledge document (and its chunks) by id.

Destructive and not reversible. Look up ids with list_knowledge. Returns {deleted} indicating whether a matching document was removed.