Tools are capabilities available to the AI during a session. Diagnostics configure which tools are enabled. Some tools are mandatory and always available.
Parallel Tool Calls
The AI can use up to 5 tools in a single response, executing them in parallel. This reduces round trips — for example, the AI can run multiple database queries at once, or promote a result while starting a new query. Each tool's result appears as a separate entry in the conversation.
PROMPT_USER must always be used alone. If the AI combines PROMPT_USER with other tools, it is asked to retry.
| Tool | Mandatory | Description |
|---|---|---|
| QUERY_DATABASE | Yes | Run SQL queries against the client database |
| PROMPT_USER | Yes | Present findings or ask the user for clarification |
| GET_OBJECT_METADATA | No | Retrieve documentation and SQL for a data object by table name |
| GET_MEASURE_METADATA | No | Retrieve documentation and SQL for a measure by identifier. When a measure is instantiated on multiple reports, prefers reports with "compass" in the name or description, then breaks ties by most recent instantiation. The response includes the report name, instantiation date, and report date range. |
| SEARCH_DATA_MODEL | No | Search for data objects and measures by keyword |
| FULL_SEARCH_DATA_MODEL | No | Deep search across all definitions, revision history comments, and layers. Use when SEARCH_DATA_MODEL does not find what you need — this searches the entire definition JSON and revision comments, not just names and descriptions. |
| SEARCH_ARTICLES | No | Search knowledge base articles by keyword |
| READ_ARTICLE | No | Read the full contents of a knowledge base article |
| PROMOTE_FINDING | No | Give a query result a title, description, and optional chart |
| SET_DISPOSITION | No | Set the structured disposition for the session (only available when a disposition schema is defined) |
Article Tools
SEARCH_ARTICLES and READ_ARTICLE give the AI access to the knowledge base articles managed under Configuration. When either (or both) of these tools is enabled for a diagnostic, the system prompt automatically includes a listing of all available articles with their names and summaries, so the AI knows what reference material exists.
SEARCH_ARTICLES
Performs a case-insensitive substring search across article names, summaries, and bodies. Returns every matching article with its summary and up to 3 matching paragraph snippets from the body as context. Single-keyword searches work best — the search matches the exact string provided, so multi-word queries require an exact substring match and are unlikely to produce results.
READ_ARTICLE
Returns the full contents of a named article (name, summary, and body). The article name is matched case-insensitively.
Presentation Tools
These tools are available in the presentation builder workspace. They are separate from session tools and focus on organizing findings into slides. All presentation tools are always available — there is no tool selection for presentations.
| Tool | Description |
|---|---|
| PROMPT_USER | Present findings or ask the user for clarification |
| LIST_FINDINGS | List findings available for the presentation (supports --unused-only flag) |
| GET_FINDING_DETAILS | Get full details of a specific finding (description, SQL, data rows) |
| ADD_FINDINGS_TO_SLIDE | Assign findings to a slide by index (supports --insert flag) |
| DELETE_SLIDE | Remove a slide and move its findings to the unused pool |
| SET_SLIDE_LAYOUT | Set the layout type for a finding slide (not applicable to text slides) |
| SET_TEXT_SLIDE | Create or update a text-only slide with markdown content (supports --insert flag) |
| STYLE_FINDING | Update the title, description, or chart instructions for a presentation finding. Uses --uuid (required) plus at least one of --title, --description, --chart_instructions; pass an empty string to clear a field |
Chart Types
A chart configuration is set by PROMOTE_FINDING when a finding is created, by STYLE_FINDING in the presentation builder, and by a user through the finding edit panel. Five chart types are available, each with its own requirements:
| Type | Requires | Also supports |
|---|---|---|
bar |
Non-empty categoryFields and 1–4 numeric measureFields |
stacked, dataLabels, and altMeasureFields (numeric columns drawn as dots on a secondary axis) |
column |
Same as bar, rendered vertically |
Same as bar |
timeseries |
categoryFields whose first field is a date, and 1–4 numeric measureFields |
Category fields beyond the date group the data into multiple lines. Multiple measure fields cannot be combined with grouping fields |
scatter |
Exactly 2 numeric measureFields; categoryFields optional, used for point labels |
denominatorField, a numeric column controlling bubble size, which renders a bubble chart |
singleValue |
Exactly 1 measureFields, no categoryFields, and a query returning exactly 1 row |
color — one of red, green, gold, blue, grey, defaulting to blue |
Every chart type also accepts:
fieldFormat— per-column formatting, keyed by column name. Each entry takes an optionalunit("number","percent", or"dollar"),precision(0–6 decimal places), andlabelthat overrides the displayed column name. Applied to axis labels, tooltips, data labels, series names, and table headers.height— percentage of the available content height, 10–100. Not supported forsingleValue.width— percentage of the available content width, 10–100. In theside-by-side-chartslayout this instead controls the proportion each of the two charts receives.