Find the tables relevant to a question and return their DDL.

Prefer this over trying to read the whole schema. The schema is far larger than the part of it any one question needs, and sending all of it costs context you will want for the answer. Pass the user's question in natural language, not a table name guess: this ranks on column names, types and the schema's own comments.

Returns the highest-scoring tables with their columns and keys, plus the foreign-key edges between the returned tables, which is what you need to write the joins.

On failure or a disappointing result:

• If a table you know you need is missing from the results, call describe_table with its name. Retrieval ranks, and a needed table can fall below the cutoff; describe_table is the escape hatch and does not depend on the ranking.

• If nothing looks relevant, re-ask with the domain words the user used (for example "reseller", "purchase order", "pay history") before widening limit. Raising limit costs tokens and rarely fixes a vocabulary mismatch.

• Do not invent table names. If you cannot find it here, say so.

Return full detail for one table by name.

Use this when you already know the table name: either search_schema returned it and you need the complete column list, or search_schema did not return it and you believe it exists anyway. This does not use the ranking, so it is the reliable way to reach a table that retrieval scored poorly.

Accepts either a qualified name ("sales.salesorderheader") or a bare one ("salesorderheader"). Returns columns with types and comments, the primary key, foreign keys out, and the foreign keys pointing in, which is how you find the tables that join to this one.

On failure:

• "No table named ..." means it does not exist under that name. The error lists close matches; try one of those. Do not retry the same name, and do not guess a third spelling. Fall back to search_schema with a description of what the table should contain.

Plan a SELECT without executing it.

Use this before run_query when the query touches a large table, has no WHERE clause, or joins several tables, so you can see the cost before committing to it. The query is planned only; no rows are read and nothing is executed. EXPLAIN ANALYZE is deliberately not offered, because it would run the statement.

Read total_cost as a relative number, useful for comparing two phrasings of the same query rather than as a time.

On failure:

• "Blocked: ..." means the same read-only policy as run_query rejected it. Rewrite as a plain SELECT.

• A "column does not exist" error means the schema assumption was wrong. Call describe_table and fix the column names.

Execute a read-only SELECT and return the rows.

Use this once you know which tables and columns you need. If you do not yet know, call search_schema first rather than guessing table names; a query against a table that does not exist wastes a round trip.

Only a single SELECT is accepted. WITH is fine as long as the whole statement is read-only. Anything else, including INSERT/UPDATE/DELETE, DDL, statement stacking, and DML hidden inside a CTE, is rejected before it reaches the database.

On failure:

• "Blocked: ..." means the statement violated the read-only policy. The message names the offending construct. Rewrite as a plain SELECT; do not retry the same statement.

• A syntax or "column does not exist" error means the schema assumption was wrong. Call describe_table on the table in question and correct the column names rather than guessing again.

• A statement timeout means the query was too expensive. Call explain_query to see the plan, then add a WHERE clause or aggregate.

Results are capped. When truncated is true the rows shown are a prefix, not the answer; narrow the query instead of treating them as complete.