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