---
title: "Tools Reference"
slug: "product-manual-compass-tools-reference"
updated: 2026-10-29T17:59:53Z
published: 2026-10-29T17:59:53Z
canonical: "docs.ursahealth.com/product-manual-compass-tools-reference"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ursahealth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools Reference

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](/v1/docs/product-manual-compass-apps) 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](/v1/docs/product-manual-compass-objects) 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 optional `unit` (`"number"`, `"percent"`, or `"dollar"`), `precision` (0–6 decimal places), and `label` that 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 for `singleValue`.
- `width` — percentage of the available content width, 10–100. In the `side-by-side-charts` layout this instead controls the proportion each of the two charts receives.