analytics

Direct link to the right account page for anything not doable in chat: billing, browser upload, report management. Hand the user the link and guide them.

{
  "type": "object",
  "properties": {
    "section": {
      "type": "string",
      "enum": [
        "home",
        "billing",
        "upgrade",
        "create",
        "upload",
        "reports"
      ],
      "description": "Where to send the user"
    }
  },
  "required": []
}

Platform documentation and info: how it works, tiers, usage.

{
  "type": "object",
  "properties": {
    "topic": {
      "type": "string",
      "description": "Topic: platform, manual, connectors, or a docs section"
    }
  },
  "required": [
    "topic"
  ]
}

AI help desk: which analysis fits your question, interpreting results, fixing errors. Multi-turn.

{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "Your question or request"
    }
  },
  "required": [
    "message"
  ]
}

Get your data in. Pass `data` as an array of row objects to create the dataset immediately and get a dataset_ref ready for create_analysis; omit it to get an upload link for a file only the user can reach. Add replace_ref (uuid://ID:KEY) with data to REFRESH an existing dataset in place; schedules and tools holding that reference read the new data on their next run.

{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "description": "Rows as an array of flat objects, creates the dataset in one call",
      "items": {
        "type": "object"
      }
    },
    "replace_ref": {
      "type": "string",
      "description": "uuid://ID:KEY of an existing dataset to overwrite in place with `data` (the push/refresh mode)"
    },
    "expires_in": {
      "type": "integer",
      "description": "Token expiration in seconds",
      "default": 300
    }
  }
}

List and search your uploaded datasets, with fuzzy matching on name, description, and tags. Returns each dataset's uuid:// reference for use in create_analysis and run_analysis.

{
  "type": "object",
  "properties": {
    "search": {
      "type": "string",
      "description": "Search by name, description, or tags"
    },
    "limit": {
      "type": "integer",
      "description": "Max results",
      "default": 20
    }
  }
}

Browse the analyses you can run: the ones you commissioned plus the platform Standard Library (prebuilt tools; each result tagged source:'own' or 'standard_library'). Plain-language match; no query lists everything, your own first. Nothing fits? Commission it with create_analysis.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Plain-language search over your library + the Standard Library; omit to list everything"
    }
  }
}

Get an analysis's parameter schema. ALWAYS call before run_analysis.

{
  "type": "object",
  "properties": {
    "tool_name": {
      "type": "string",
      "description": "Name of the analysis"
    }
  },
  "required": [
    "tool_name"
  ]
}

Run an analysis on your data. Returns a shareable interactive report URL with statistics you can cite, re-run and share, and the method named.

{
  "type": "object",
  "properties": {
    "tool_name": {
      "type": "string",
      "description": "Name of the analysis to run"
    },
    "estimate_id": {
      "type": "string",
      "description": "Optional. The estimate this run answers (from an estimate page); the run's objects are then written beside the estimate's for comparison."
    },
    "taskList": {
      "type": "object",
      "description": "Execution inputs. Call tools_schema first for the analysis-specific fields.",
      "properties": {
        "inputs": {
          "type": "object",
          "properties": {
            "dataset": {
              "type": "string",
              "description": "Dataset reference: uuid://UUID:KEY from datasets_upload/datasets_list"
            },
            "userContext": {
              "type": "object",
              "description": "Business context: objective (what you want to learn, required) and company"
            },
            "column_mapping": {
              "type": "object",
              "description": "Analysis-specific column mapping, see tools_schema"
            },
            "module_parameters": {
              "type": "object",
              "description": "Analysis-specific parameters, see tools_schema"
            }
          }
        }
      }
    }
  },
  "required": [
    "tool_name",
    "taskList"
  ]
}

Commission a NEW analysis built for your question. tier is REQUIRED. The user picks. Easiest: fuzzy_request (plain language) + dataset_ref + tier. Snapshot = instant automated report (~2-10 min). JSON = a fast computed answer, numbers + method, re-runnable tool you own (~5 min). Brief = the computed answer on a one-page report: chart, numbers, method (~7 min). Deck = commissioned deep analysis, a durable re-runnable module you own (30-45 min). Failed builds are never billed.

{
  "type": "object",
  "properties": {
    "fuzzy_request": {
      "type": "string",
      "description": "Plain-language description of the analysis you want"
    },
    "dataset_ref": {
      "type": "string",
      "description": "Single-dataset URI: 'uuid://UUID:KEY'"
    },
    "datasets_refs": {
      "type": "object",
      "description": "Multi-dataset URIs keyed by role"
    },
    "tier": {
      "type": "string",
      "enum": [
        "snapshot",
        "json",
        "brief",
        "deck"
      ],
      "description": "snapshot = instant report (~2-10 min); json = fast computed answer (~5 min, default); brief = one-page report of the answer (~7 min); deck = commissioned re-runnable module (30-45 min)"
    },
    "specification": {
      "type": "object",
      "description": "Full 11-field spec (legacy path, prefer fuzzy_request)"
    },
    "column_mapping": {
      "type": "object",
      "description": "Optional semantic-to-real column map (hint only)"
    },
    "notes": {
      "type": "string",
      "description": "Optional context for the build, constraints, definitions, or preferences the analyst agents should honor"
    }
  },
  "required": []
}

Modify an EXISTING analysis into a new version: reword the question, swap the method, or add a variable. Pass tool_name + changes (plain language). Rebuilds on the analysis's own dataset by default; the original stays put. Returns pipeline tracking. Follow with build_status.

{
  "type": "object",
  "properties": {
    "tool_name": {
      "type": "string",
      "description": "The analysis to modify (from discover_tools or your library)"
    },
    "changes": {
      "type": "string",
      "description": "What to change, in plain language, e.g. 'also break it down by region' or 'use a random forest instead'"
    },
    "tier": {
      "type": "string",
      "enum": [
        "snapshot",
        "json",
        "brief",
        "deck"
      ],
      "description": "Optional, change the depth of the new version"
    },
    "dataset_ref": {
      "type": "string",
      "description": "Optional, rebuild against a different dataset ('uuid://UUID:KEY')"
    }
  },
  "required": [
    "tool_name",
    "changes"
  ]
}

START HERE for a new question: free, ~30 s. A rough answer over a sample plus the layout of the complete package, every place named with the question it will answer, and a page link. Then review_estimate with the user.

{
  "type": "object",
  "properties": {
    "objective": {
      "type": "string",
      "description": "The user's question in their own words"
    },
    "dataset_ref": {
      "type": "string",
      "description": "'uuid://UUID:KEY'"
    },
    "layout_objective": {
      "type": "string",
      "description": "Optional: how the page should read"
    },
    "tool_names": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Optional library tools, each checked with check_tool_fit"
    }
  },
  "required": [
    "objective",
    "dataset_ref"
  ]
}

The estimate as you review it WITH the user: the question as understood, the estimated answer (sample, marked), every place and its question, the page link, a review checklist. Before order_analytics_package.

{
  "type": "object",
  "properties": {
    "estimate_id": {
      "type": "string"
    }
  },
  "required": [
    "estimate_id"
  ]
}

Apply the user's layout wishes to the estimate's page through the layout agent; a new named arrangement, nothing overwritten, no number changes.

{
  "type": "object",
  "properties": {
    "estimate_id": {
      "type": "string"
    },
    "instructions": {
      "type": "string",
      "description": "What to change, in the user's words"
    }
  },
  "required": [
    "estimate_id",
    "instructions"
  ]
}

A read of the data (average, count, total, highest/lowest by group, a value in a month) answered in this response, in seconds. Not a read -> immediate=false with the reason; continue with decide_path.

{
  "type": "object",
  "properties": {
    "objective": {
      "type": "string"
    },
    "dataset_ref": {
      "type": "string"
    }
  },
  "required": [
    "objective",
    "dataset_ref"
  ]
}

Step 0 for a new question: which path answers it on this data. One record: route (reuse | answer | package | ask | none), a score with its reason for each of answer, package, ask and none, the compiled read plan when it is a read, the method family and the library's tool fit when it is a package, and the one question to ask when something is missing. Deterministic, read-only.

{
  "type": "object",
  "properties": {
    "objective": {
      "type": "string"
    },
    "dataset_ref": {
      "type": "string"
    }
  },
  "required": [
    "objective",
    "dataset_ref"
  ]
}

Before estimating: how did we answer this objective before, on this data or any data? Prior packages and library runs with their tools, mappings, bespoke module names, method and verdicts. Platform-wide, read-only.

{
  "type": "object",
  "properties": {
    "objective": {
      "type": "string"
    },
    "dataset_ref": {
      "type": "string"
    },
    "k": {
      "type": "integer",
      "default": 10
    }
  },
  "required": [
    "objective"
  ]
}

Before naming a library tool: does it fit THIS dataset for THIS question? Column mapping, missing required inputs, method-fit verdict, the places it delivers. Read-only.

{
  "type": "object",
  "properties": {
    "tool_name": {
      "type": "string"
    },
    "dataset_ref": {
      "type": "string"
    },
    "objective": {
      "type": "string"
    }
  },
  "required": [
    "tool_name",
    "dataset_ref"
  ]
}

Order what the estimate promised after reviewing it: library tools that fit, a bespoke build, or both, computed on the whole dataset; one reviewed page delivered. Credits per tool run; failed runs never billed.

{
  "type": "object",
  "properties": {
    "estimate_id": {
      "type": "string"
    },
    "tool_names": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "bespoke": {
      "type": "boolean",
      "default": false
    },
    "layout_objective": {
      "type": "string"
    }
  },
  "required": [
    "estimate_id"
  ]
}

Read an analytics package back: status, every run under it, the report link once delivered.

{
  "type": "object",
  "properties": {
    "package_id": {
      "type": "string"
    }
  },
  "required": [
    "package_id"
  ]
}

Run a delivered package again, on its own data or new data: the same tools, the same curated objects, the same layout, as a new package with its own link.

{
  "type": "object",
  "properties": {
    "package_id": {
      "type": "string"
    },
    "dataset_ref": {
      "type": "string"
    }
  },
  "required": [
    "package_id"
  ]
}

List and search the objects you own across every question: the curated charts, tables and figures of each delivered package, grouped by objective.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string"
    },
    "limit": {
      "type": "integer",
      "default": 50
    },
    "include_dropped": {
      "type": "boolean",
      "default": false
    }
  }
}

Check a commissioned build in-chat: stage progress, queue position, rejection reason if the data didn't match the objective, honest ETA, report link when delivered.

{
  "type": "object",
  "properties": {
    "pipeline_id": {
      "type": "integer",
      "description": "pipeline_id from create_analysis"
    },
    "track_token": {
      "type": "string",
      "description": "Token from the tracking URL"
    }
  },
  "required": []
}

Ask a question across all your delivered analyses: a synthesized answer with citations back to specific reports.

{
  "type": "object",
  "properties": {
    "question": {
      "type": "string",
      "description": "Plain-language question to answer from your report library"
    }
  },
  "required": [
    "question"
  ]
}

Your report library: every analysis delivered, with status and links. Pass semantic_query to search report content in plain language.

{
  "type": "object",
  "properties": {
    "semantic_query": {
      "type": "string",
      "description": "Natural-language search over your reports' content"
    },
    "limit": {
      "type": "integer",
      "description": "Max results",
      "default": 10
    }
  }
}

Query your org's data warehouse free: browse the catalog (tables with column roles + computed metrics), semantically find data, plain-language ask, or named templates. Requires warehouse enablement (business plans).

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "ask",
        "query",
        "queries",
        "catalog",
        "find"
      ]
    },
    "question": {
      "type": "string"
    },
    "query": {
      "type": "string"
    },
    "params": {
      "type": "object"
    }
  },
  "required": [
    "action"
  ]
}

Standing re-runs of analyses you own: action='create' (weekly/monthly against a re-runnable data reference, connector:// or an https:// link; report emailed after each run), 'list', or 'cancel'.

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "create",
        "list",
        "cancel"
      ],
      "description": "What to do"
    },
    "tool_name": {
      "type": "string",
      "description": "create: the analysis to schedule"
    },
    "dataset_ref": {
      "type": "string",
      "description": "create: re-runnable reference (connector:// or https://)"
    },
    "cadence": {
      "type": "string",
      "enum": [
        "weekly",
        "monthly"
      ]
    },
    "column_mapping": {
      "type": "object"
    },
    "schedule_id": {
      "type": "integer",
      "description": "cancel: from action='list'"
    }
  },
  "required": [
    "action"
  ]
}

Get a shareable browser link for a report, viewable without authentication.

{
  "type": "object",
  "properties": {
    "processing_id": {
      "type": "string",
      "description": "Processing ID from run_analysis / reports_list"
    }
  },
  "required": [
    "processing_id"
  ]
}

Browse a delivered report's individual cards (charts, tables, insights) inline in chat.

{
  "type": "object",
  "properties": {
    "processing_id": {
      "type": "string",
      "description": "The report's processing id, returned by run_analysis or build_status"
    }
  },
  "required": [
    "processing_id"
  ]
}