Query tool - Cognite Docs

The Query tool enables Atlas AI agents to discover and interact with data modeling instances across your entire data model. Agents can list, search, aggregate, or retrieve instances 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 you select in the project, so you can switch location filters without updating your agent configuration.

Public preview: The Query tool is currently in public preview testing and is subject to change.

Configuring the tool

When you add the Query tool to your agent in the Agent builder, 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 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. If you leave Views empty, discovery includes every view in that data model.

Instance spaces

Spaces 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. 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.

Tool	When to use
Query time series data points	Use the Query tool to identify a time series, then pass its ID to this tool to retrieve data points.
Answer document questions	Use the Query tool to find and retrieve files, then use this tool to answer questions from their contents.
Summarize documents	Use the Query tool to retrieve specific files, then use this tool to generate a summary of their contents.

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, and use the evaluation feature to confirm behavior after reconfiguring.

​Configuring the tool

​Data models

​Instance spaces

​Operations

​Example queries

​Filtering, aggregation, and sorting

​Traversing related data

​Combining tools

​Related information

Configuring the tool

Data models

Instance spaces

Operations

Example queries

Filtering, aggregation, and sorting

Traversing related data

Combining tools

Related information