aggregate_table_data
ChatGPTAggregate table data with grouping dimensions and metrics. NO ROW LIMIT. This is the correct way to extract financial totals - use aggregation instead of raw queries which are limited to 500-1000 rows. Args: table_id: The ID of the table to aggregate dimensions: List of fields to group by (e.g., ["Reporting Date", "DR_ACC_L1", "Department L1"]) metrics: List of metric definitions with field and aggregation type. Example: [{"field": "Amount", "agg": "SUM"}, {"field": "Amount", "agg": "COUNT"}] filters: Optional list of filter objects to narrow the data. Example: [{"name": "Scenario", "values": ["Actuals"], "is_excluded": false}] Aggregation types supported: - SUM: Sum of values - AVG: Average of values - MIN: Minimum value - MAX: Maximum value - COUNT: Count of records - COUNT_DISTINCT: Count of distinct values Returns aggregated data grouped by the specified dimensions. Unlike get_records_by_filter (500 rows) or execute_query (1000 rows), aggregation has NO row limit and returns properly computed totals. If a dimension field causes a server error, this tool automatically retries with compatible alternative fields (e.g., DR_ACC_L1.5 instead of DR_ACC_L1). The response will note any field substitutions that were made. IMPORTANT: Never fall back to execute_query or get_records_by_filter for financial totals. Those tools have row limits and will return incomplete data. Always use this tool and retry with different dimension fields if needed. Example for P&L extraction: dimensions: ["Reporting Date", "DR_ACC_L1", "DR_ACC_L2", "Department L1"] metrics: [{"field": "Amount", "agg": "SUM"}] filters: [ {"name": "Scenario", "values": ["Actuals"], "is_excluded": false}, {"name": "DR_ACC_L0", "values": ["P&L"], "is_excluded": false} ]
detect_anomalies
ChatGPTRun automated anomaly detection via profiling (no raw data fetch). Args: table_id: The ID of the table to analyze Detects various anomaly types: - Numeric outliers (statistical) - Missing value patterns - Duplicate detection - Temporal anomalies (gaps, future dates) - Categorical anomalies (rare values, unexpected nulls) - Referential integrity issues Returns findings with severity levels (critical, high, medium, low) and recommendations for remediation.
execute_query
ChatGPTExecute a custom query against Finance OS. Returns max 1000 rows. Args: table_id: The ID of the table to query (used for authorization) query: SQL-like query string to execute Supports: - SELECT with column selection - WHERE clauses with conditions - ORDER BY for sorting - GROUP BY with aggregations - LIMIT (automatically capped at 1000) Note: Some operations may be restricted based on user permissions.
get_aggregated_data_by_alias
ChatGPTAggregate an aliased table's data with grouping dimensions and metrics. NO ROW LIMIT. Server-computed grouped aggregation over a table addressed by alias — the by-alias twin of get_aggregated_data_by_id. Dimensions, metric fields, and filters reference field aliases (from list_aliased_fields), not raw field names or ids. Args: alias: Table alias (e.g., 'ap', 'bank_transactions', 'trial_balance'). dimensions: List of field aliases to group by (e.g. ['region', 'segment']). metrics: List of {field, agg} specs, e.g. [{"field": "amount", "agg": "SUM"}]. agg is one of: SUM, COUNT, COUNT_UNIQUE, UNIQUE_VALUES, AVG, MIN, MAX. Multiple metrics are supported — each is returned as its own column per group (one value per metric per row). Use at most one aggregation per field per call: requesting two aggregations of the same field (e.g. SUM and AVG of one field) is rejected — make a separate call for each. SUM and AVG are rejected on a text field (Text/BigText) — use COUNT, COUNT_UNIQUE, UNIQUE_VALUES, MIN, or MAX on text fields instead. filters: Optional list of {name, values, is_excluded?} objects addressed by field alias, where values takes one of two forms: Value list — match any of the listed values (set membership / IN): {"name": "scenario", "values": ["Actuals", "Budget"]} Set is_excluded: true to exclude the listed values (NOT IN). Advanced — a condition tree for comparisons, ranges, and text matching: {"name": "amount", "values": {"type": "advanced", "val": [ {"condition": "gte", "value": "1000"}, {"condition": "lt", "value": "5000", "operator": "and"} ]}} Each val entry is {condition, value, operator?}: - condition: equals, dn_equals (does not equal), contains, dn_contains, bw (begins with), ew (ends with), gt, gte, lt, lte, in, range (exclusive between), total_range (inclusive between), is null. - value: a string for scalar conditions; a list of strings for in; a two-item [from, to] list of strings for range and total_range. Numbers/dates are passed as strings (e.g. epoch "1750000000"); the backend casts per field. For is null, set value to "" (it is ignored downstream). - operator: how this condition chains with the previous one, 'and' (default) or 'or' to start an alternative branch. is_excluded applies to value lists only, not advanced filters. Returns aggregated rows grouped by the requested dimensions. Note: not all aliased tables support aggregation (works well with ap, bank_transactions, trial_balance).
get_aggregated_data_by_id
ChatGPTAggregate a table's data with grouping dimensions and metrics. NO ROW LIMIT. Server-computed grouped aggregation over a table addressed by id. Dimensions, metrics, and filters reference numeric field ids (from get_fields_by_id), not field names. Before manually aggregating for a named KPI (revenue, margin, expenses, budget variance, headcount, ratios), check list_business_metrics — if a matching metric covers the question, get_business_metric_data returns server-computed values directly. Use this tool for ad-hoc dimensional slices the metric catalog does not expose. Args: table_id: The id of the table to aggregate. dimensions: List of field ids to group by (e.g. [101, 102]). metrics: List of {field_id, agg} specs, e.g. [{"field_id": 103, "agg": "SUM"}]. agg is one of: SUM, COUNT, COUNT_UNIQUE, UNIQUE_VALUES, AVG, MIN, MAX. Multiple metrics are supported — each is returned as its own column per group (one value per metric per row). Use at most one aggregation per field per call: requesting two aggregations of the same field (e.g. SUM and AVG of one field) is rejected — make a separate call for each. SUM and AVG are rejected on a text field (Text/BigText) — use COUNT, COUNT_UNIQUE, UNIQUE_VALUES, MIN, or MAX on text fields instead. filters: Optional list of {field_id, values, is_excluded?} objects, where values takes one of two forms: Value list — match any of the listed values (set membership / IN): {"field_id": 104, "values": ["Actuals", "Budget"]} Set is_excluded: true to exclude the listed values (NOT IN). Advanced — a condition tree for comparisons, ranges, and text matching: {"field_id": 105, "values": {"type": "advanced", "val": [ {"condition": "gte", "value": "1000"}, {"condition": "lt", "value": "5000", "operator": "and"} ]}} Each val entry is {condition, value, operator?}: - condition: equals, dn_equals (does not equal), contains, dn_contains, bw (begins with), ew (ends with), gt, gte, lt, lte, in, range (exclusive between), total_range (inclusive between), is null. - value: a string for scalar conditions; a list of strings for in; a two-item [from, to] list of strings for range and total_range. Numbers/dates are passed as strings (e.g. epoch "1750000000"); the backend casts per field. For is null, set value to "" (it is ignored downstream). - operator: how this condition chains with the previous one, 'and' (default) or 'or' to start an alternative branch. is_excluded applies to value lists only, not advanced filters. Returns aggregated rows grouped by the requested dimensions. Unlike get_data_by_id (capped row fetch), aggregation has no row limit and returns server-computed totals.
get_currency_rates
ChatGPTFX rates snapshot (USD base). Single point in time, no history. Thin wrapper over /foreign_exchange/v1/currency-rates. The backend returns the most-recent rate set the org has loaded — there is no period/date parameter. The response includes a date field indicating when the snapshot was captured; the snapshot may lag wall-clock time depending on how the org keeps its rate table up to date. Currency coverage varies by org (the rate set only includes currencies the org has actually loaded — not a fixed global list). Inspect the response before assuming a given ISO code is present. For historical or period-specific FX, this endpoint is not suitable.
get_data_by_alias
ChatGPTGet rows from an aliased table (addressed by alias) with optional column selection. KEY ADVANTAGE: Use select to return ONLY the columns you need. A typical table has 228 columns — selecting 5 reduces tokens by ~95%. Args: alias: Table alias (e.g., 'ap', 'bank_transactions') select: List of field aliases to return (e.g., ['amount', 'payment_status']). If None, returns all columns (not recommended). filters: Optional list of {name, values, is_excluded?} objects addressed by field alias, where values takes one of two forms: Value list — match any of the listed values (set membership / IN): {"name": "payment_status", "values": ["Paid", "Pending"]} Set is_excluded: true to exclude the listed values (NOT IN). Advanced — a condition tree for comparisons, ranges, and text matching: {"name": "amount", "values": {"type": "advanced", "val": [ {"condition": "gte", "value": "1000"}, {"condition": "lt", "value": "5000", "operator": "and"} ]}} Each val entry is {condition, value, operator?}: - condition: equals, dn_equals (does not equal), contains, dn_contains, bw (begins with), ew (ends with), gt, gte, lt, lte, in, range (exclusive between), total_range (inclusive between), is null. - value: a string for scalar conditions; a list of strings for in; a two-item [from, to] list of strings for range and total_range. Numbers/dates are passed as strings (e.g. epoch "1750000000"); the backend casts per field. For is null, set value to "" (it is ignored downstream). - operator: how this condition chains with the previous one, 'and' (default) or 'or' to start an alternative branch. is_excluded applies to value lists only, not advanced filters. limit: Max rows (default 100, max 500) offset: Rows to skip for pagination (default 0) ALWAYS use select to minimize token usage. Use field aliases (from list_aliased_fields), not raw field names.
get_data_by_id
ChatGPTGet rows from a table (addressed by id) with optional column selection. Fetches raw rows — use for row-level inspection or when the user wants specific records. For totals/grouped breakdowns use get_aggregated_data_by_id (no row limit); for named KPIs check list_business_metrics first. Args: table_id: The id of the table (from list_data_models). select: List of field ids to return (e.g. [101, 103], from get_fields_by_id). Raw tables are wide (~200 columns); project to the few you need. Omit to return all columns (not recommended). filters: Optional list of {field_id, values, is_excluded?} objects, addressed by numeric field id (from get_fields_by_id), where values takes one of two forms: Value list — match any of the listed values (set membership / IN): {"field_id": 104, "values": ["Actuals", "Budget"]} Set is_excluded: true to exclude the listed values (NOT IN). Advanced — a condition tree for comparisons, ranges, and text matching: {"field_id": 105, "values": {"type": "advanced", "val": [ {"condition": "gte", "value": "1000"}, {"condition": "lt", "value": "5000", "operator": "and"} ]}} Each val entry is {condition, value, operator?}: - condition: equals, dn_equals (does not equal), contains, dn_contains, bw (begins with), ew (ends with), gt, gte, lt, lte, in, range (exclusive between), total_range (inclusive between), is null. - value: a string for scalar conditions; a list of strings for in; a two-item [from, to] list of strings for range and total_range. Numbers/dates are passed as strings (e.g. epoch "1750000000"); the backend casts per field. For is null, set value to "" (it is ignored downstream). - operator: how this condition chains with the previous one, 'and' (default) or 'or' to start an alternative branch. is_excluded applies to value lists only, not advanced filters. limit: Max rows (default 100, max 500). offset: Rows to skip for pagination (default 0).
get_distinct_values_by_alias
ChatGPTGet the distinct values of an aliased table field, addressed by alias. Args: alias: Table alias field_alias: Field alias (from list_aliased_fields)
get_distinct_values_by_id
ChatGPTGet the distinct values of a table field, addressed by numeric field id. Args: table_id: The id of the table (from list_data_models). field_id: The numeric field id (from get_fields_by_id). Returns a sorted list of the unique values found in the specified field.
get_field_distinct_values
ChatGPTGet distinct values for a field. Useful for understanding categorical data. Args: table_id: The ID of the table field_name: The name of the field to get distinct values for limit: Maximum number of distinct values to return (default 100) Returns a list of unique values found in the specified field, along with their counts.
get_fields_by_id
ChatGPTGet the fields (columns) of a table, addressed by id. Args: table_id: The id of the table (from list_data_models). Returns the table's name and alias plus, for each field: id (numeric field id, used by the by-id tools), alias (business-friendly name, empty if none), name, type, and description.
get_org_users
ChatGPTGet users in the organization with roles and departments. Default returns ~9 KB (50 users) flattened to: - id, first_name, last_name, email, is_active - role (ADMIN, CONTRIBUTOR, VIEWER, SUPER_ADMIN) - department (FINANCE_FPA, SALES, R&D, etc.) - job_role (VP, DIRECTOR, BOARD_MEMBER, etc.) Useful for understanding org structure and tailoring responses. Args: include_full: When True, returns the raw envelope (~60 KB) including permission_groups, telemetry, badge info.
get_plugin_catalog
ChatGPTIMPORTANT: This tool MUST be called at the START of every new conversation, before any other tool. It returns the catalog of all available skills, agents, and workflows on this server. Use the catalog to understand what capabilities are available. When a user's request matches a skill, call load_skills_and_md_files with the skill's path to retrieve the full instructions for executing it. Returns JSON with: - skills: list of available skills with their paths and metadata - directory_tree: the full plugin content directory structure
get_records_by_filter
ChatGPTFetch specific records matching filters. Hard limit: 500 rows. Args: table_id: The ID of the table to query filters: Dictionary of field names to filter values. Example: {"status": "active", "amount": {">": 1000}} limit: Maximum rows to return (default 100, max 500) Filter operators supported: - Equality: {"field": "value"} - Comparison: {"field": {">": 100, "<": 1000}} - In list: {"field": {"in": ["a", "b", "c"]}} - Null check: {"field": {"is_null": true}} - Like pattern: {"field": {"like": "%pattern%"}}
get_sample_records
ChatGPTGet a random sample of records for quick inspection. Max 20 rows. Args: table_id: The ID of the table to sample n: Number of sample records to return (default 20, max 20) Useful for: - Quick data exploration - Understanding data format and content - Validating assumptions about the data
get_table_schema
ChatGPTGet schema (columns, types) for a Finance OS table. Args: table_id: The ID of the table to get schema for Returns detailed column information including: - Column names and data types - Nullable flags - Primary key information - Foreign key relationships
get_workflow_guide
ChatGPTGet guided workflows for common financial analysis tasks. Call without arguments to see all available workflows. Call with a workflow name to get step-by-step guidance. Use this tool when: - A user is new and wants to know what they can do - A user asks for help or says "what can you do?" - You need guidance on which tools to use for a specific task - A user wants a financial summary, expense analysis, revenue trends, etc. Args: workflow_name: Optional. One of: getting-started, financial-summary, expense-analysis, revenue-trends, budget-comparison, data-quality, explore-data, api-test
list_aliased_fields
ChatGPTList the fields of an aliased table, with aliases and descriptions. Args: alias: Table alias (e.g., 'financials', 'ap', 'trial_balance') Returns field information including: - alias: business-friendly name for the field - name: original raw field name - type: data type - description: what this field means in business context PREFER this over get_fields_by_id when an alias is available — it gives business context.
list_business_metrics
ChatGPTStart here for any named-KPI question (revenue, margin, expenses, budget variance, headcount, ratios). Returns the org's defined metrics with business context, status, dimensions, and formulas — so you can pick the right metric and call get_business_metric_data instead of manually aggregating raw tables. Returns a flat list. Each metric contains: - id, name, description, category, kind (USER/BASE/CALC) - time_aggregation (how the metric rolls up over time), format - dimensions[]: which fields the metric can be sliced by - status_info: { status, source_warning?, error_message?, last_updated } Use status_info to triage: a non-empty error_message flags a broken metric, and a source_warning flags source tables that aren't configured/mapped or only partially loaded (so get_business_metric_data may return 0 rows or incomplete data). Note: status_info is a triage hint, not a contract with the data endpoint. Some metrics with an error_message still return values from get_business_metric_data, and some clean ones come back empty — verify by calling get_business_metric_data when in doubt. Best starting point for understanding what KPIs the org tracks.
list_data_models
ChatGPTList all data models (tables) available to the caller — with or without an alias. For named-KPI questions (revenue, margin, expenses, budget variance, headcount, ratios), prefer list_business_metrics first — the metric catalog typically answers them directly. Use this tool for raw-data exploration or when no metric covers the question. Each entry carries both identities: the numeric id used by the by-id (raw) endpoints and the alias used by the by-alias endpoints (empty when a table has no alias). Tables with an alias also offer human-readable field aliases and descriptions — prefer the by-alias tools for those. Args: name: Optional table name (case-insensitive exact match) for a cheap single-table lookup. Empty array if nothing matches. alias: Optional alias (e.g., "financials", "ap") — same filter, matched against the table's alias. has_alias: Optional — true returns only tables that have an alias. Without filters, returns every table. Pair with get_fields_by_id(id) or list_aliased_fields(alias) for the field list.
list_filebox
ChatGPTList filebox items (folders, files, templates, lookup tables) in the org. Useful for discovering org-level content structure — top-level folders like "Actuals", "Reports", "Configuration", "Analysis". Each item has a parent (parent id or null), so the tree can be reconstructed. Args: include_full: When True, also returns permissions[], tags_config, bucket — about 8× larger (~280 KB). Default trim returns ~36 KB (199 items: id, parent, name, is_folder, scenario, use_type, is_process_root).
list_finance_tables
ChatGPTList all available Finance OS tables. Returns a list of tables with their IDs, names, and basic metadata. Use this to discover what data is available for analysis.
list_xl_functions
ChatGPTList the XL functions visible to the calling user. XL functions are the named aggregations that Excel DR.GET formulas reference as their first argument: =DR.GET(<FunctionName>, "[Dimension]", CellRef, ...). Never guess or hardcode a function name — always discover it here. Each entry carries: - name: the exact token to use as DR.GET's first argument - template: the owning table {id, name} — pass template.id to get_fields_by_id to learn which dimension fields are valid in the formula's "[Dimension]" pairs - vals / aggfun: the value field(s) being aggregated and how - default_agg_datefield: id of the date field used for default time aggregation (resolve to a name via get_fields_by_id) Validate dimension values with get_distinct_values_by_id before writing them into a workbook. Args: include_archived: Include archived functions (default False — archived functions can't be used in new formulas). include_full: Return raw records including authorship metadata (default False trims last_edited_by).
load_skills_and_md_files
ChatGPTLoad skill and workflow instructions by their relative paths. Call this tool immediately whenever the user's request matches a skill from the plugin catalog. Do not wait for the user to ask for it — as soon as you identify the right skill, load it and follow its instructions. The loaded content contains step-by-step execution guides that tell you which tools to call and in what order. Args: paths: List of relative paths from the plugin root directory. Example: ["skills/intelligence/SKILL.md", "agents/finance-analyst.md", "CLAUDE.md"] Returns JSON mapping each requested path to its full text content, or null if the file was not found.
profile_categorical_fields
ChatGPTProfile categorical fields: distinct values, NULL counts, cardinality. Args: table_id: The ID of the table to profile fields: Optional list of specific fields to profile. If None, profiles all categorical fields. Returns for each categorical field: - Distinct value count (cardinality) - Most frequent values with counts - Null count and percentage - Uniqueness ratio
profile_numeric_fields
ChatGPTProfile numeric fields: MIN, MAX, AVG, SUM, COUNT, outliers. Args: table_id: The ID of the table to profile fields: Optional list of specific fields to profile. If None, profiles all numeric fields. Returns for each numeric field: - Min, max, mean, median, std deviation - Sum and count - Null count and percentage - Outlier detection (values beyond 3 standard deviations) - Distribution percentiles (25th, 50th, 75th, 95th, 99th)
profile_table_summary
ChatGPTGet comprehensive summary: row count, column stats, data quality metrics. Args: table_id: The ID of the table to profile Returns: - Total row count - Column count and types breakdown - Missing value statistics - Data quality score - Memory usage estimate
