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

# Query tool

> Configure the Query tool in the Atlas AI agent builder so agents can list, search, aggregate, and retrieve data modeling instances.

The Query tool enables Atlas AI agents to discover and interact with
[data modeling](/cdf/dm/dm_concepts) instances
across your entire data model. Agents can list, search, aggregate, or retrieve
[instances](/cdf/dm/dm_concepts/dm_spaces_instances#space) using a single,
schema-aware tool that works across multiple data models and views.

By default, the tool uses the data models and instance spaces for the
[location filter](/cdf/locations/index) you select in the project, so you can
switch location filters without updating your agent configuration.

<Warning>
  **Public preview:** The Query tool is currently in [public preview](/cdf/product_feature_status) testing and is subject to change.
</Warning>

## Configuring the tool

When you add the Query tool to your agent in the
[Agent builder](/cdf/atlas_ai/guides/atlas_ai_agent_building), configure these
settings.

| Setting           | Description                                                                                                        |
| ----------------- | ------------------------------------------------------------------------------------------------------------------ |
| Tool name         | A name that identifies the tool's purpose.                                                                         |
| Tool instructions | Instructions that tell the agent when to use this tool and how to choose data modeling views, filters, and limits. |

You must also configure data models and instance spaces.

### Data models

The data models setting controls which
[data models](/cdf/dm/dm_concepts/dm_containers_views_datamodels#data-models)
the agent can query.

| Setting                    | Description                                                                                                                                                                                                                                                                     |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Defined by user's location | The tool uses the data models for your selected location filter. This is the default.                                                                                                                                                                                           |
| Configure manually         | You provide a fixed list of data models. For each model, you can fill in the **Views** fields to limit discovery to specific [views](/cdf/dm/dm_concepts/dm_containers_views_datamodels#views). If you leave **Views** empty, discovery includes every view in that data model. |

### Instance spaces

[Spaces](/cdf/dm/dm_concepts/dm_spaces_instances#space) organize data into
separate, access-controlled partitions. The instance spaces setting controls
which spaces the Query tool can read from.

| Setting                                            | Description                                                                                     |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Inherit scope based on user's location             | The tool reads from the instance spaces for your selected location filter. This is the default. |
| Inherit scope based on user's access rights in CDF | The tool reads from every space you can access in CDF.                                          |
| Follow access scope defined manually               | You specify exactly which spaces the tool can read from.                                        |

## Operations

This table describes the operations available in the Query tool.

| Operation             | What it does                                                                                |
| --------------------- | ------------------------------------------------------------------------------------------- |
| `list_views`          | Discovers which data modeling views the agent can query.                                    |
| `get_view_schema`     | Returns the fields and relations a data modeling view contains.                             |
| `get_filter_docs`     | Returns help text for writing correct filters.                                              |
| `list_instances`      | Retrieves instances from one data modeling view.                                            |
| `search_instances`    | Finds instances in one data modeling view that match a text query.                          |
| `aggregate_instances` | Counts and summarizes data in one data modeling view without listing every instance.        |
| `retrieve_instances`  | Fetches specific instances when the agent already knows the instance space and external ID. |

## Example queries

This table shows how different question types map to Query tool operations. Understanding this mapping helps you write skills and instructions that guide the agent to the right operation.

| Question type                                 | Operation             | Example                                                    |
| --------------------------------------------- | --------------------- | ---------------------------------------------------------- |
| List assets or equipment matching a condition | `list_instances`      | "Show me all pumps with status OPEN in Unit 4"             |
| Find records by name or description text      | `search_instances`    | "Find work orders mentioning 'bearing failure'"            |
| Count or summarize records                    | `aggregate_instances` | "How many open work orders are there per equipment type?"  |
| Fetch a specific record you already know      | `retrieve_instances`  | Follow-up retrieval after identifying an instance ID       |
| Discover what views are available             | `list_views`          | Used by the agent before querying an unfamiliar data model |
| Inspect what fields a view contains           | `get_view_schema`     | Used by the agent to confirm field names before filtering  |

### Filtering, aggregation, and sorting

The Query tool supports server-side filtering, aggregation, and sorting. Configuring your skills to use these capabilities keeps queries fast and results focused.

Use `aggregate_instances` when a question asks for a count, total, or grouped summary. For example, use a server-side aggregation to answer "How many overdue work orders are there by site?" rather than listing all work orders and counting them. Skills can reinforce this by including a vocabulary mapping: when the user asks "how many," use `aggregate_instances`.

Use filters to narrow results before returning them. A question like "Show me all high-priority work orders from the last 30 days" should apply both a priority filter and a date filter in the query rather than retrieving all records and filtering afterward.

### Traversing related data

To answer questions that span multiple views, such as finding the time series linked to an asset or the work orders associated with a piece of equipment, the agent uses multiple tool calls. The first call retrieves the primary record. Subsequent calls use IDs from that result to fetch related instances.

Document this traversal pattern in a skill when it applies to a common question type, so the agent does not need to infer the correct sequence at runtime.

## Combining tools

To complete tasks that include multiple data types, use the Query tool with
other tools from the [Agent tools library](/cdf/atlas_ai/references/atlas_ai_agent_tools).

| Tool                                                                                       | When to use                                                                                                |
| ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| [Query time series data points](/cdf/atlas_ai/references/atlas_ai_agent_tools#query-tools) | Use the Query tool to identify a time series, then pass its ID to this tool to retrieve data points.       |
| [Answer document questions](/cdf/atlas_ai/references/atlas_ai_agent_tools#analysis-tools)  | Use the Query tool to find and retrieve files, then use this tool to answer questions from their contents. |
| [Summarize documents](/cdf/atlas_ai/references/atlas_ai_agent_tools#analysis-tools)        | Use the Query tool to retrieve specific files, then use this tool to generate a summary of their contents. |

<Tip>
  If you are using multiple Query knowledge graph tools, the Query tool can replace them.
  The Query tool works across multiple data models and views, so you can consolidate
  your setup, move any view-specific instructions into a [skill](/cdf/atlas_ai/guides/atlas_ai_agent_configure_skills), and use the
  [evaluation feature](/cdf/atlas_ai/guides/atlas_ai_agent_evaluating) to confirm
  behavior after reconfiguring.
</Tip>

## Related information

* [Building agents](/cdf/atlas_ai/guides/atlas_ai_agent_building)
* [Manage locations](/cdf/locations/index)
* [Agent tools library](/cdf/atlas_ai/references/atlas_ai_agent_tools)
* [Querying in data modeling](/cdf/dm/dm_concepts/dm_querying)
* [Cognite knowledge graph](/cdf/dm/dm_concepts/dm_property_graph)
* [Agent runtime versions](/cdf/atlas_ai/references/atlas_ai_agent_runtime_versions)