The Query tool enables Atlas AI agents to discover and interact with Cognite Data Model instances. Your agent can discover views, inspect properties on views, and list, search, aggregate, or retrieve instances. You can combine the Query tool with other tools in the Agent tools library so that your agent can complete a wider range of tasks. When set to Defined by user’s location (default), the tool automatically picks up the data models and instance spaces configured for the user’s selected location. This means a single agent can work across different data models and locations without any changes to the tool configuration.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.
Configuring the tool
When you add the Query tool to your agent in the Agent builder, you must configure the following settings.- 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 views, filters, and limits.
Data models
The data models setting controls which data models the agent can query. Choose one of the following:- Defined by user’s location (default): The tool automatically uses the data models associated with the user’s selected location.
- Configure manually: You provide a fixed list of data models. You can optionally restrict each model to specific Views — leave Views empty to allow discovery across all views in that model.
Instance spaces
Spaces are how CDF organizes data into separate, access-controlled partitions. The instance spaces setting controls which spaces the Query tool can read data from. In the Agent builder, choose one of the following:- Inherit scope based on user’s location (default): The tool reads from the spaces associated with the user’s selected location.
- Inherit scope based on user’s access rights in CDF: The tool reads from all spaces the user has access to.
- Follow access scope defined manually: You specify exactly which spaces the tool can read from.
Using the operations
The following table lists which operations the agent can use with the Query tool.| Operation | Purpose |
|---|---|
list_views | Discover which views the agent can query. |
get_view_schema | See which fields and relations a view contains. |
get_filter_docs | Get help text for writing correct filters. |
list_instances | Retrieve instances from one view. |
search_instances | Find instances in one view that match a text query. |
aggregate_instances | Count and summarize data in one view without listing every instance. |
retrieve_instances | Fetch specific instances when the agent already knows space and external ID. |
Upgrading from Query knowledge graph
Query knowledge graph tools require one tool per view. The Query tool replaces them with a single, schema-aware tool that can work across your entire data model. Consolidate your toolsRemove your existing Query knowledge graph tools and add one Query tool. A single Query tool can point to multiple data models and covers all views by default — use Views to restrict discovery if needed. Move domain knowledge to agent instructions
Any instructions you added to individual Query knowledge graph tools — for example, “To find P&IDs, filter for files with type = ‘pid’” — are plant or domain knowledge. Move them to the agent’s general instructions (or a skill) so they are available regardless of which view the agent queries. Re-run your evaluations
After reconfiguring, use the evaluation feature to confirm the agent behaves as expected and catch any regressions that may require updates to the agent instructions or skills.