Start here for any question about the data. Returns the few tables and views the question needs, as compact DDL to write SQL against, scoped to the caller: objects and columns they may not read are absent, not ranked low. Pass principal and roles whenever you know who is asking. Returns 'ddl' (put it in your SQL prompt), 'objects' (the names chosen), 'explain' (score and reason per object) and 'selected' / 'total_objects'. Reads table structure only, never rows. Next: write one SELECT against 'ddl' and call run_query with the same principal and roles; call describe_object if a table needs more columns than the compact DDL shows. If the right table is missing, raise top_k or rephrase rather than writing SQL against a table that was not returned.

List every table and view this caller may read: 'objects' holds each one's name, kind (table or view), column count and description, with 'count' visible out of 'total_objects'. Use it to show what data exists, or when select_schema did not return what you expected. It returns no DDL and no rows, and on a large database it is long: to answer a question, call select_schema instead. Pass principal and roles; restricted objects are absent for callers without the role.

Full DDL (all visible columns, keys, comments) for one table or view, if the caller may read it. Use it when select_schema's compact DDL is not enough. A restricted or missing object returns the same 'not available' error, so its existence is not revealed.

Execute one read-only SELECT and return the rows (capped by max_rows). Write the SQL against the DDL select_schema returned for the same caller. Refuses writes, multiple statements, and any table or column the caller may not read, with an error that says so ('not available to this caller'), which you can pass on to the user instead of reporting 'no results'.

For questions about what text says when no column records it, e.g. 'which complaints ask for a refund'. Runs one read-only SELECT through the same checks as run_query, then has the server's model read one text column of the returned rows and either keep the rows that meet a criterion or add a short answer per row. Returns columns, rows, how many rows were judged, and which text was sent to the model. Off unless the server enables it (SCHEMAGATE_MCP_SEMANTIC=1), because the row text goes to the model provider; at most 200 rows are judged. Use plain run_query whenever a column already holds the answer.

Question in, rows out: selects the schema, writes the SQL with the server's own configured model, and runs it, all scoped to the caller. Only available when the server has a model configured; most clients should use select_schema then run_query with their own model instead.

Re-read the database structure (new tables, changed columns, changed grants) and swap the index in. Call it after a migration or a permission change, or when health shows the catalog is stale; it is not needed before ordinary questions. Takes no arguments, never changes the database, and can take seconds on a large schema. Returns {ok: true, objects, seconds}. If the database is unreachable it returns {ok: false, kept_previous: true, error}: the previous catalog stays in service.

Server status: whether the catalog is loaded, how many objects it holds, the database dialect, and audit-log counts. Takes no arguments; safe to call any time.