add_dataset_transformations
ChatGPTStage new transformation steps on a dataset table as a draft. Changes are written to a DRAFT, not the live dataset. The live dataset is untouched until the user opens the draft in the editor and clicks Save to publish it (or Discard to revert). New steps are added on top of the dataset's existing transformations; SQL for PROMPT and ADD_COLUMN steps is generated automatically from the natural language prompt. Args: table_name: The backend name of the table to transform. sql_transformations: List of transformation step objects. Each step must have a "type" field. Supported types: - ADD_COLUMN: Add a new column. Requires: type, columnName, description, prompt. Example: {"type": "ADD_COLUMN", "columnName": "Region", "description": "Add column Region", "prompt": "add a column called Region"} - RENAME_COLUMN: Rename a transformation-added column. Requires: type, columnName (original), value (new name). Example: {"type": "RENAME_COLUMN", "columnName": "Locality", "value": "Location"} Note: Cannot rename source columns — only columns added by transformations. - MODIFY_COLUMN_TYPE: Change a transformation-added column's data type. Requires: type, columnName, value (new type). Example: {"type": "MODIFY_COLUMN_TYPE", "columnName": "Amount", "value": "NUMERIC"} Note: Cannot modify source column types — only columns added by transformations. - LOOKUP: Join a column from another table. Requires: type, columnNames (match keys in current table), dataset (other table backend name), datasetColumnNames (match keys in other table), datasetSelectColumnNames (columns to bring over). Example: {"type": "LOOKUP", "columnNames": ["rep_id"], "dataset": "Employees", "datasetColumnNames": ["rep_id"], "datasetSelectColumnNames": ["rep_name"]} - PROMPT: Apply a complex SQL transformation described in natural language. Requires: type, prompt. Example: {"type": "PROMPT", "prompt": "filter rows where status = 'active' and sort by created_date desc"} Returns: A confirmation string containing an "Open in editor" markdown link. Always include this link verbatim in your reply so the user can review the draft and Save or Discard it. - On success: the draft is created with the requested transformations. - If some steps have errors, the draft is kept (with the failing steps noted) so the user can fix them in the editor; the link is still returned. - An error string (no link) if permissions, SQL generation, or draft creation fails.
create_board
ChatGPTValidate and save a new board (report) to the tenant. Runs board-structure and chart-type validation before saving; returns consolidated errors if validation fails. The board is saved as a draft and opened in edit mode for the user to review; it is not published until the user clicks Save in the editor. Args: board: A complete DTML board object (dict). Required keys: - id (int): Board ID. Use 0 for a new board; use an existing ID to update. - name (str): Display name of the board. - description (str): Short description of the board. - attributes (dict): Board-level settings — dateOption, dimMap, draft, etc. - dtmlCharts (list[dict]): Chart objects. Each chart needs id, name, type, metricNames, versionNames, rows, columns, attributes, and type-specific config. - template (dict): Must contain template.name (str), template.type ("PAGE"), and template.style.gridLayout with order (list[str]) and rows (dict of row objects). Each row needs height (number) and cells (list of {id: str, width: 1-12}). Cell ids must match chart ids; row widths should sum to ≤12. Returns: - On success, a confirmation string containing the new board id AND a clickable "Open board" markdown link. Always include this link verbatim in your reply to the user so they can open the board directly. - A consolidated error/warning string if validation fails (board is NOT saved). - An error message (str) if saving fails after validation.
describe_metrics
ChatGPTRetrieve metadata for a specific list of metrics identified by their backend (system) names. Returns the same fields as search_metrics but skips semantic search — use this when you already know the exact system names of the metrics you need. Args: metric_names: List of metric backend (system) names to look up. Example: ["total_revenue", "churn_rate", "arr"] Returns: list[dict]: List of metric metadata objects, each with keys: - system_name: The system name of the metric - display_name: The user-facing display name of the metric - description: Description of the metric (can be None if not available) - domain: The domain of the metric (MONITORING or PLANNING) - applicable_dimensions: The dimensions you can break the metric by - data_format: The data format configuration of the metric (can be None), with keys: - currency: Currency code (e.g. "USD") - display_unit: Display unit (e.g. "K", "M", "B") - digits_after_decimal: Number of decimal places - blank_value_format: Format for blank/null values - zero_format: Format for zero values - negative_value_format: Format for negative values - direction: Whether higher or lower values are better (HIGHER_IS_BETTER or LOWER_IS_BETTER) - localCurrencyEnabled: Whether local currency conversion is enabled - constantCurrencyEnabled: Whether constant currency conversion is enabled Notes: - Only returns metrics the current user is permitted to access - Metrics not found or not permitted are silently excluded from the result
get_board
ChatGPTRetrieve the full DTML board object for an existing board by its ID. Use this tool to fetch the current state of a board before editing it. Args: board_id: The ID of the board to retrieve. Must be a valid non-zero integer. Returns: - The full board object (dict) if found — includes id, name, description, attributes, charts, template, and all other board properties. - An error message (str) if the board ID is invalid or the board is not found.
get_dataset_column_values
ChatGPTFetch distinct values for a specific column in a dataset. Use this to verify exact spelling and case of values before filtering or applying conditional logic. The values reflect the current transformed view of the table. IMPORTANT: Always call list_dataset_columns first to verify the exact column name (correct spelling and casing) before calling this tool. Never guess or assume the column name. Args: table_name: The backend name of the table. column_name: The exact column name as returned by list_dataset_columns. Returns: list: Distinct values found in the column. Returns an error string if the column or table is not found.
get_dataset_current_transformations
ChatGPTFetch the current transformation steps applied to a dataset. Use this to see what transformations already exist and their positions (indexes), which is required before editing an existing transformation. Args: table_name: The backend name of the table. Returns: list[dict]: List of transformation steps, each with: - position: The index of the step (use this as the id when editing) - type: The transformation type (ADD_COLUMN, RENAME_COLUMN, MODIFY_COLUMN_TYPE, LOOKUP, PROMPT) - attributes: The step details (columnName, value, sql, prompt, etc.)
get_dimension_values
ChatGPTList all unique values of a specific dimension. Use this tool when you need to know the actual values a dimension can take (e.g., all department names, all region codes, all product categories). Args: dimension_name: The system name of the dimension to retrieve values for. Example: "Department" Returns: list: All unique values for the specified dimension.
get_list_data
ChatGPTFetch a single List's full contents: its config (column order, column formulas / "rules", unique key) and its rows (with formula columns evaluated), optionally scoped to a version. To compare a list across two versions, call this once per version with the version-specific list id (obtained from get_lists for that version). A list id is globally unique and already identifies that version's copy, so no version needs to be passed here. Args: list_id: The numeric id of the list (from get_lists, resolved within the target version). Returns: dict: The list object including config (columnOrder, columnFormulae, uniqueKey) and rows.
get_lists
ChatGPTRetrieve the Lists in Drivetrain, optionally scoped to a specific version. A List is a user-editable data table (rows of data plus rules such as column formulas). Lists are version-scoped: the same list has different rows in different versions. To inspect a version's lists, pass that version's version_id (the id from list_versions); omit it to use the current model. Use this first to discover the id and name of a list before fetching its data with get_list_data. Note that a list's id is different in each version, so resolve the id within the target version. Args: version_id: Optional. The numeric id of the version (the id from list_versions). Omit for the current model. Returns: list[dict]: Each item is a list object with keys: id, name, displayName, description.
get_model_dtml
ChatGPTRetrieve the raw DTML for model-relevant sections. Returns the current state of the planning model as a DTML dictionary containing: meta, folder, metrics, templates, and scenarios. Use this tool to read the full model DTML before making changes via update_model_dtml. You must specify which section to fetch. Call this tool multiple times if you need more than one section. Parameters: section (required): One of "meta", "folder", "metrics", "templates", "scenarios". Returned sections: - meta: Plan metadata (period, duration, plan name, start date, tenant info) - folder: Hierarchical folder tree containing modules. Each module has name, displayName, calculations (list of "metrics.VariableName" references), dimensions, scenarios, etc. - metrics: Array of all metric/variable definitions. Each has name, displayName, type, formulae, dimensions, domain (PLANNING/MONITORING), metricSource, timeSummary, dimensionSummary, dataFormat, category, etc. - templates: Array of module templates defining visual layout. Each has moduleName, templateJson (stringified JSON with body.elements array of SECTION/METRIC/BLANK elements). - scenarios: Array of planning scenario definitions. Returns: dict: DTML with the requested section.
list_dataset_columns
ChatGPTList all columns and their data types for a specific table. Returns the post-transformation schema (includes columns added by transformations). Args: table_name: The backend name of the table (from list_datasets). Returns: dict: Table schema with columns list, each column having: - name: Column name - type: Data type (STRING, NUMERIC, DATE, DATETIME, TIMESTAMP, etc.)
list_datasets
ChatGPTList all available data connectors and their datasets in Drivetrain. Each connector represents a data source like Google Sheets, Snowflake, Salesforce, etc., and includes all datasets (tables) belonging to that connector along with their display and backend names. Args: None Returns: list[dict]: List of data connectors, each with keys: - id: The connector instance ID - name: The backend name of the connector - datasetDisplayName: The display name of the connector - datasets: List of datasets for this connector, each with: - displayName: The user-facing display name of the dataset - name: The backend name of the dataset (use this when referencing the dataset in transformations)
list_dimensions
ChatGPTList all dimensions in the system along with their metadata and attributes. Dimensions are the categorical axes used to slice and filter metrics (e.g., Department, Region, Product). Each dimension includes its metadata and its attributes, which are themselves also dimensions. Use this tool to discover what dimensions are available and understand how they relate to each other. Args: None Returns: list[dict]: List of dimensions with their metadata and attributes.
list_scenarios
ChatGPTRetrieve the list of available scenarios for the tenant. Scenarios represent different planning or forecasting versions of data (e.g., "Base Case", "Optimistic", "Pessimistic"). Args: None Returns: list[dict]: List of scenario objects, each with keys: - name: The system name of the scenario - display_name: The user-facing display name of the scenario
list_versions
ChatGPTArgs: query: The user's query, provide the entire user query to the tool. Do not alter the user query in any way. Processes the list of versions to return version objects with id, system_name and displayName. Identify system name of version from the list by matching display name of the version with the user query if applicable. The id is the version's numeric identifier — pass it as version_id to version-scoped tools (e.g. get_lists, get_list_data). Do not mention system names or ids in your response.
query_metrics
ChatGPTFetch raw numerical data for one or more metrics in a single combined TESS call. Today's date: 2026-07-10 Current year: 2026-01-01 to 2026-12-31 Use this for any metric data fetch — pass a single metric if the user asks about one metric, or a list of metrics if they need several at once (e.g., Revenue, Gross Profit, OpEx, NOI). All metrics share the same date range, granularity, versions, dimensions, scenarios, and filters. Args: metrics: List of metric system_names to fetch. For a single metric, pass a one-element list. Example: ["total_revenue"] or ["total_revenue", "gross_profit"] start_date: Start of date range in "YYYY-MM-DD" format. For MONTHLY/QUARTERLY/YEARLY granularity, always the first day of a month. For DAILY/WEEKLY granularity, any date is allowed. end_date: End of date range in "YYYY-MM-DD" format. For MONTHLY/QUARTERLY/YEARLY granularity, always the last day of a month. For DAILY/WEEKLY granularity, any date is allowed. granularity: Time aggregation — one of: DAILY, WEEKLY, MONTHLY, QUARTERLY, YEARLY versions: List of version system_names. Example: ["Actual", "Budget"] dimensions: (Optional) List of dimension names to break ALL metrics by. Only dimensions common to all metrics will work. scenarios: (Optional) List of scenario backend names to filter by. Defaults to ["Base_Case"] if not provided. Example: ["Base_Case", "Best_Case"] filters: (Optional) Dict of dimension name to list of values to filter by. Returns: dict: Keyed by metric system_name, it is a nested json structure. If a metric fails, its value will be an error string instead.
resolve_dimensions
ChatGPTDetects the dimension for a metric when the user mentions dimension values but not the dimension name itself. Uses semantic search to reverse-engineer which dimension the user's search phrases belong to. Use this when the user mentions a value like "America" or "Marketing" and you need to figure out which dimension (Region, Department, etc.) it maps to for a given metric. Args: metric_name: The system name of the metric (as returned by search_metrics). search_phrases: 1-3 phrases extracted from the user query that likely refer to dimension values. Exclude the metric name from these phrases. Examples: - "Revenue for America" → ["America", "USA"] - "Expenses for AWS" → ["AWS", "Amazon"] - "Hiring in Marketing" → ["Marketing"] Returns: - A list of "Dimension: Value" strings showing detected matches. Example: ["Region: America", "Department: Marketing", "Department: Sales"] - An error message (str) if the metric is not found, has no dimensions, or no matching dimension values were found.
search_docs
ChatGPTSearch Drivetrain's internal product documentation (how-to articles, feature guides, concept explanations) for a natural-language question. Use ONLY when the user is explicitly asking a documentation / help question — e.g. - "How does scenario planning work?" - "What is the difference between a dataset and a dimension?" - "Where do I configure RBAC?" - "How do I set up a forecast?" Do NOT call this tool: - While creating, editing, or designing a board / report / dashboard — the metric, dimension, version, and chart-spec tools already return everything needed. - To look up a metric definition, formula, or applicable dimensions — use describe_metrics instead. - To find dimension values or hierarchies — use list_dimensions / get_dimension_values. - As "background context" or "to be safe" — if the user hasn't asked a doc question, this tool adds latency without improving the answer. If you are in the middle of a report-creation, modelling, or dataset-transformation flow and feel tempted to call this, do not. The specialised tools for that flow have the information you need. Args: question: The user's documentation question, phrased as a natural-language query. Returns: - Relevant passages from Drivetrain's internal documentation.
search_metrics
ChatGPTRetrieve a list of available business metrics, each with its display name, description, type and applicable dimensions using relevant search phrases. Metrics are quantitative values that measure business performance—such as revenue, churn rate, average deal size, and active users. Use this tool when you need to explore measurable aspects of business performance or understand which key metrics are available for analysis. Search for relevant metrics using key phrases extracted from the user's query. Uses semantic search to find ALL metrics that match the intent above a relevance threshold. Args: query: The user's query, provide the entire user query to the tool. Do not alter the user query in any way. search_phrases: List of search phrases from the user query. Extract complete phrases that capture the concept, not individual words. Examples: ["monthly recurring revenue"], ["cash burn rate"], ["year over year growth"] Returns: list[dict]: List of relevant metrics, each with keys: - system_name: The system name of the metric (these are the internal names of the metrics) - display_name: The display name of the metric (these are the user facing names of the metrics) - description: Description of the metric (can be None if not available) - domain: The domain of the metric (MONITORING or PLANNING) - applicable_dimensions: The dimensions you can break the metric by - data_format: The data format configuration of the metric (can be None), with keys: - currency: Currency code (e.g. "USD") - display_unit: Display unit (e.g. "K", "M", "B") - digits_after_decimal: Number of decimal places - blank_value_format: Format for blank/null values - zero_format: Format for zero values - negative_value_format: Format for negative values - direction: Whether higher or lower values are better (HIGHER_IS_BETTER or LOWER_IS_BETTER) - localCurrencyEnabled: Whether local currency conversion is enabled - constantCurrencyEnabled: Whether constant currency conversion is enabled Important: - Returns ALL metrics that are similar to the search phrases - Could return 1 metric or 20+ metrics depending on query specificity - More specific phrases = fewer, more precise results - Generic phrases = more results Usage: - Extract the key concept from the user's query as a natural phrase - Keep phrases together: "monthly recurring revenue" NOT ["monthly", "recurring", "revenue"] - Can provide synonyms as separate items: ["headcount", "employee count"] Examples: - User: "Show me revenue for last month" → search_phrases: ["revenue"] Returns: Total Revenue, Revenue Growth, ARR Revenue, etc. - User: "What's our MRR?" → search_phrases: ["monthly recurring revenue"] Returns: Monthly Recurring Revenue, MRR, Recurring Revenue, etc. - User: "Cash burn rate in Q1" → search_phrases: ["cash burn rate"] Returns: Cash Burn Rate, Burn Multiple, Cash Flow, etc. - User: "Show me headcount" → search_phrases: ["headcount", "employee count"] Returns: Total Headcount, Employee Count, FTE Count, etc.
update_board
ChatGPTEdit an existing board (report) in the tenant. Creates a draft copy of the board with your changes — the original board is untouched until the user clicks Save in the UI. The board must already exist — its ID must be a valid non-zero ID. Runs board-structure validation before saving; returns consolidated errors if validation fails. Use this tool when modifying an existing report — adding/removing charts, changing layout, updating board name or attributes, etc. For creating new boards, use create_board instead. Args: board: A complete DTML board object (dict) with the existing board's ID. Required keys: - id (int): The existing board ID. Must be non-zero. - name (str): Display name of the board. - description (str): Short description of the board. - attributes (dict): Board-level settings — dateOption, dimMap, draft, etc. - dtmlCharts (list[dict]): Chart objects. Each chart needs id, name, type, metricNames, versionNames, rows, columns, attributes, and type-specific config. - template (dict): Must contain template.name (str), template.type ("PAGE"), and template.style.gridLayout with order (list[str]) and rows (dict of row objects). Each row needs height (number) and cells (list of {id: str, width: 1-12}). Cell ids must match chart ids; row widths should sum to ≤12. Returns: - On success, a confirmation string containing the draft board id AND a clickable "Open board" markdown link. Always include this link verbatim in your reply to the user so they can open the board directly. - A consolidated error/warning string if validation fails (nothing is saved). - An error message (str) if the board ID is missing/zero or saving fails.
update_dataset_transformations
ChatGPTEdit existing transformation steps on a dataset table as a draft. Use get_dataset_current_transformations first to get the current step positions (indexes), then pass those positions as ids with one replacement step for each. Changes are written to a DRAFT, not the live dataset. The live dataset is untouched until the user opens the draft in the editor and clicks Save to publish it (or Discard to revert). Args: table_name: The backend name of the table. ids: List of position indexes of the transformations to replace (from get_dataset_current_transformations). new_sql_transformations: List of replacement transformation step objects (same format as add_dataset_transformations). The number of ids must match the number of new steps — each id maps to its corresponding replacement step. Returns: A confirmation string containing an "Open in editor" markdown link. Always include this link verbatim in your reply so the user can review the draft and Save or Discard it. - On success: the transformations are edited on the draft. - If some steps have errors, the draft is kept (with the failing steps noted) so the user can fix them in the editor. - An error string (no link) if permissions, validation, or SQL generation fails.
validate_formula
ChatGPTValidate the syntax of a Drivetrain planning formula before saving it to a variable. Always call this before saving a new or changed formula to a variable. Checks that: - All functions are used correctly (correct number of args, valid syntax) - Metric references (metrics.X) are syntactically valid - Dimension filters are correctly formed - Date arithmetic uses supported functions (not raw arithmetic on dates) Note: validates syntax only — does not check whether referenced metric system names exist in the tenant. Use search_metrics to verify metric names exist. Args: rhs: The right-hand side formula expression. Backend syntax — use metrics.SystemName, dims.t, time.moduleActualsEndDate. Do NOT include the "metrics.X = " left-hand side. Example: "if(dims.t <= time.moduleActualsEndDate, 0, metrics.Base_Salary * metrics.Bonus_Rate)" lhs_metric_name: (Optional) The left-hand side metric name. Defaults to "metrics.Test_Metric". Use the actual target variable's system name for more accurate validation. scenario: (Optional) Scenario context for validation. Defaults to "Base_Case". Returns: - "✅ Formula is valid: <formula>" if validation passes - "❌ Formula validation errors:\n - <error details>" if validation fails - "⚠️ ..." for service/connectivity errors
