add_graph_to_dashboard
ChatGPTSave a BlazeSQL-compatible graph from an executed SQL result and add it as a dashboard tile. Use only when the user asks to add/save the graph to a dashboard or clearly names a dashboard target. Do not use dashboard tools as ordinary data discovery; for normal data questions, use schema discovery and execute_sql first. Prefer query_request_id from execute_sql so the saved dashboard graph matches the result shape you already inspected. If the user names a dashboard but not its ID, use list_dashboards/search_dashboards only to identify that specific dashboard. dynamicChartCode is optional and stored on the saved BlazeSQL query for custom chart rendering in the app. Use helpers.theme for theme-aware neutral colors: backgroundColor, secondarySurfaceColor, textColor, secondaryTextColor, borderColor, gridColor, and accentColor. Use helpers.theme.secondarySurfaceColor for tooltip or raised-surface backgrounds. These values automatically follow the host app's light, dark, or custom theme. Use helpers.theme.borderRadius, which is 4, as the default corner radius for containers and chart marks. For Plotly bar charts, use marker.cornerradius: helpers.theme.borderRadius; helpers.renderPlotly also applies this default when it is omitted. The widget already shows graphConfig.name above the chart. Do not repeat that name in Plotly layout.title; reserve the chart title area for a genuinely different note. When a horizontal legend sits below a chart that has an x-axis title, place the legend at y: -0.32 or lower and leave at least 100px of bottom margin so the labels do not overlap. For click drill-downs that reveal a list of records or items, keep the widget's outer size stable: replace the chart with a separate detail page inside the same container, include a clear Back control that restores the chart, and do not append the list below or beside the chart. In Codex, visualization iframes are content-sized rather than given a stable height to fill. For non-map Plotly charts, always return helpers.renderPlotly({ data, layout, config }); do not call Plotly.newPlot directly or set height, min-height, or aspect-ratio on the container or chart root. Let the helper establish and report the chart height while the width stays responsive. helpers.renderPlotly clears the visualization container and returns a Promise that resolves to the rendered chart element. Attach Plotly click handlers in .then((chartElement) => { ... }); for a same-size drill-down, measure that rendered chart only when opening the detail page, scroll inside the detail page, and call Plotly.Plots.resize(chartElement) when restoring the chart.
blazesql_query
ChatGPTExecute a natural language query against your BlazeSQL database. Prefer passing the user's request directly; avoid specifying tables/columns unless the user explicitly requested them. Returns the generated SQL and query results.
blazesql_query_progress
ChatGPTInternal: Returns live progress updates for the currently running BlazeSQL query. Intended for the BlazeSQL UI only.
check_query_status
ChatGPTCheck the status of a long-running BlazeSQL query. Use when blazesql_query returns a job_id indicating the query is still running. Call this tool with the job_id to get the results once ready, or get an updated status if still running.
describe_tables
ChatGPTReturn full metadata (columns, data types, descriptions, knowledge notes) for specific tables in the selected BlazeSQL database. Provide each table as an exact reference, preferably schema.table (e.g. public.orders). A bare table name works only when it is unique across schemas. Use this before writing SQL against specific tables.
execute_sql
ChatGPTExecute one read-only SQL statement against the selected BlazeSQL database, or execute an existing saved/dashboard query by query_id. Provide exactly one of query or query_id. Format raw SQL for readability with appropriate line breaks and consistent indentation. For ordinary data questions, write SQL in query after schema discovery. Use query_id only when the user specifically asks to run an existing saved query/dashboard tile or has selected one. To learn the schema, use the schema discovery tools (list_schemas, list_tables, describe_tables) — do NOT use execute_sql for schema discovery (e.g. information_schema, SHOW TABLES/COLUMNS, pg_catalog), unless the user explicitly asks for it or you are debugging a specific schema/metadata discrepancy. Use describe_tables first when you need table or column names. When passing raw SQL in query, include the user's original request and a step-by-step rationale for observability. When passing query_id, original_user_request and rationale are optional. If the user asks for a graph or chart, run execute_sql first, inspect the returned rows and requestId, then call graph_sql_result with that query_request_id.
graph_sql_result
ChatGPTCreate a dynamic graph from an already completed SQL result. Use this after execute_sql, once you have inspected the returned rows and requestId. Provide exactly one of query_request_id or query_id. Prefer query_request_id from execute_sql so the graph is based on the exact result the user just saw. query_id can execute and graph an existing saved BlazeSQL query. Use graphType, xAxisVariable, yAxisVariable, groupByVariable, and stacked when they map to BlazeSQL graph settings. Make the visualization interactive by default with hover/focus tooltips on chart marks. For graphType map, use the built-in helpers.createWorldBubbleMap helper for tile-backed country, city, or local bubble maps. In dynamicChartCode, data.rows is an array of objects keyed by column name; use row.date or row.metric_name, not row[0]. Use helpers.theme for theme-aware neutral colors: backgroundColor, secondarySurfaceColor, textColor, secondaryTextColor, borderColor, gridColor, and accentColor. Use helpers.theme.secondarySurfaceColor for tooltip or raised-surface backgrounds. These values automatically follow the host app's light, dark, or custom theme. Use helpers.theme.borderRadius, which is 4, as the default corner radius for containers and chart marks. For Plotly bar charts, use marker.cornerradius: helpers.theme.borderRadius; helpers.renderPlotly also applies this default when it is omitted. The widget already shows graphConfig.name above the chart. Do not repeat that name in Plotly layout.title; reserve the chart title area for a genuinely different note. When a horizontal legend sits below a chart that has an x-axis title, place the legend at y: -0.32 or lower and leave at least 100px of bottom margin so the labels do not overlap. For click drill-downs that reveal a list of records or items, keep the widget's outer size stable: replace the chart with a separate detail page inside the same container, include a clear Back control that restores the chart, and do not append the list below or beside the chart. In Codex, visualization iframes are content-sized rather than given a stable height to fill. For non-map Plotly charts, always return helpers.renderPlotly({ data, layout, config }); do not call Plotly.newPlot directly or set height, min-height, or aspect-ratio on the container or chart root. Let the helper establish and report the chart height while the width stays responsive. helpers.renderPlotly clears the visualization container and returns a Promise that resolves to the rendered chart element. Attach Plotly click handlers in .then((chartElement) => { ... }); for a same-size drill-down, measure that rendered chart only when opening the detail page, scroll inside the detail page, and call Plotly.Plots.resize(chartElement) when restoring the chart.
list_dashboards
ChatGPTList dashboards the user can access through creator, direct, team, or access-group sharing. Not for ordinary data questions; use schema tools and execute_sql unless the user asks for dashboards/reports. Returns dashboard IDs, names, descriptions, BlazeSQL URLs, access info, tile counts, selected-database query tile counts, timestamps, and refresh settings.
list_saved_queries
ChatGPTList saved queries and graphs for the selected BlazeSQL database. Not for ordinary data questions; use schema tools and execute_sql unless the user asks for saved queries/graphs. Includes queries the user created, saved, or can access through direct, team, or access-group sharing. Returns query IDs, names, descriptions, BlazeSQL URLs, graph type, access info, timestamps, variable flag, and SQL previews.
list_schemas
ChatGPTList the schemas in the selected BlazeSQL database, with schema descriptions and table counts. If the database has a single visible schema, its tables are listed too. If the full schema is small enough, the complete table/column metadata (including knowledge notes) is included automatically. Start here to discover the database, then narrow with list_tables for a schema, then describe_tables for specific tables before writing SQL.
list_tables
ChatGPTList the tables in the selected BlazeSQL database, with table descriptions and column counts. Requires one or more schema names from list_schemas. If the returned table set is small enough, the complete table/column metadata (including knowledge notes) is included automatically. Use describe_tables to get full metadata for specific tables before writing SQL.
read_dashboard
ChatGPTRead one dashboard by dashboard_id. Use only after the user names/selects a dashboard or asks to inspect one. Returns dashboard fields and ordered content tiles. Text tiles include text and layout fields. Query tiles include linked saved-query detail when the query belongs to the selected database and is accessible through the dashboard; otherwise they include omittedReason.
read_saved_query
ChatGPTRead one saved query or graph by query_id. Use only after the user names/selects a saved query/graph or asks to inspect one. Returns full SQL, BlazeSQL URL, graph config, metric config, query variables, timestamps, access info, and canExecuteWithQueryId. A query can also be read when it is reachable through an accessible dashboard tile for the selected database.
search_dashboards
ChatGPTSearch dashboards the user can access. Not for ordinary data questions; use only when the user asks for an existing dashboard/report/tile. Searches dashboard name, dashboard description, text tiles, and linked selected-database query name, description, and SQL. Returns the same summary fields as list_dashboards, plus matchedFields and matchedQueryIds.
search_saved_queries
ChatGPTSearch saved queries and graphs for the selected BlazeSQL database. Not for ordinary data questions; use only when the user asks for an existing saved query/graph. Searches query name, description, and SQL text across queries the user can access. Returns the same summary fields as list_saved_queries, plus matchedFields.
suggest_schema_context_update
ChatGPTSubmit reusable context for admin review. Suggestions do not become active context unless an admin approves them. When to use: - When feedback could usefully guide future queries beyond the current request or a few follow-ups. - This includes, but is not limited to, preferences, conventions, facts, rules, and definitions. - Prefer learnings that would have prevented a mistake, avoided future iteration, or clarified an information gap. - Do NOT use for one-off question details, transient context, or anything already covered by existing knowledge notes from the schema tools. - When execute_sql recommends a context update, call this tool to submit it; execute_sql does not submit it automatically. - Submit each recommendation once. Do not resubmit the same feedback after a successful submission. How to write good notes: - Keep each note clear, ultra concise, and general enough to apply to related future requests; focus on the 'why', with specific instructions as a last resort and always paired with a reason. - Use explicit wording like 'always' or 'never' when appropriate. - Avoid redundancy: do not repeat knowledge that another note already provides. Scope (choose the broadest correct level; do not repeat a learning across lower-level objects if a higher-level note captures it): - Database-level: omit schema, table, and column. - Schema-level: provide schema only. - Table-level: provide schema and table. - Column-level: provide schema, table, and column. - Use exact schema/table/column names from list_tables/describe_tables; always include schema when providing a table or column.
