Tools are capabilities available to the AI during a session. Diagnostics and personas 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, the other tools still run but the PROMPT_USER message is withheld, and the AI is asked to reconsider its message in light of their results before sending it alone. A response with more than 5 tools is rejected outright, with nothing run.
| 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, along with its most recent ELT history (datetime, elapsed time, row count, and any errors or warnings) and revision history (timestamp, user, and comment). |
| 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 other reports are listed alongside. The response includes the report name, instantiation date, report date range, and the measure's most recent revision history (timestamp, user, and comment). |
| 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 |
| SEARCH_ASSETS | No | Search personas, diagnostic definitions, apps, and presentations by keyword |
| DESCRIBE_ASSET | No | Describe a persona, diagnostic definition, app, or presentation by name |
| 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) |
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 |
App Tools
These tools are available in the app build workspace. They are separate from session tools and focus on writing the app rather than investigating data. All app tools are always available — there is no tool selection for apps.
| Tool | Description |
|---|---|
| PROMPT_USER | Report what the app now does, or ask the user for clarification |
| GET_OBJECT_METADATA | Retrieve documentation, SQL, and recent ELT and revision history for a data object by table name, to understand what an object means before deciding what to show |
| GET_MEASURE_METADATA | Retrieve documentation, SQL, and recent revision history for a measure by identifier, along with every report the measure is instantiated on — which is where the report name a declaration needs comes from |
| SET_FOUNDATION | Declare which objects and measures the app may read, as a comma-separated list, optionally with the feedback the app records on each. Replaces the previous list rather than adding to it. Returns the declarations the app is written and type-checked against — the exact function names, the columns that may be grouped by, and every column's type. This list is also the app's data grant at run time |
| CREATE_COMPONENT | Write the app, as a single fenced code block containing the whole thing. Type-checked and compiled before it is saved; nothing that fails is stored |
SET_FOUNDATION must be called before CREATE_COMPONENT, since it is what supplies the declarations the app is written against. An app with no declared foundation has nothing to read.
An object is named by its table name. A measure is named by its identifier, and must say which report it is read through, written as URSA-PHF-001 (VIA REPORT Readmissions FY25).
A declaration may also name feedback the app captures, written as ursa.encounter (WITH FEEDBACK isValidated int, comment string). Fields may be string, date, int, float, or json. This is what gives the app a function for writing feedback.
Object Tools
These tools are available in the Compass Object build workspace. All object tools are always available — there is no tool selection for objects.
| Tool | Description |
|---|---|
| QUERY_DATABASE | Run SQL queries against the client database |
| PROMPT_USER | Report what the object now holds, or ask the user for clarification |
| GET_OBJECT_METADATA | Retrieve documentation and SQL for a data object by table name |
| GET_MEASURE_METADATA | Retrieve documentation and SQL for a measure by identifier |
| SET_COMPASS_OBJECT | Build the object's draft from a single select, as a table or a view, with its primary key, optional column labels and descriptions, and optionally a measure type. Replaces the previous draft only once the new one has built, its key holds, and it conforms to its measure type. Returns the finished column metadata |
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.