> For the complete documentation index, see [llms.txt](https://docs.buildings.ability.abb/collection/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.buildings.ability.abb/collection/suites/space-and-assets-analytics/copilot-assistant/prompting-guide.md).

# Prompting Guide

The way you phrase a question directly affects the quality of the answer. This page explains how the Data Agent interprets requests and how to write prompts that return precise, useful results.

* how to get more accurate results
* how to get faster results
* requests should match actual measurements if possible (e.g. talking of utilization when you want people-count/occupancy metrics)

**How the Agent Interprets Your Request**

The agent parses every query for the following elements:

<table><thead><tr><th width="374">Element</th><th>Examples</th></tr></thead><tbody><tr><td><strong>Locations</strong></td><td>building, floor, room, zone, east wing, basement</td></tr><tr><td><strong>Assets or asset types</strong></td><td>sensors, meters, SmartSocket, EnergyMeter, rooms</td></tr><tr><td><strong>Metrics</strong></td><td>temperature, energy usage, occupancy, CO2, water consumption</td></tr><tr><td><strong>Time ranges</strong></td><td>last week, past quarter, between Jan 1 and Dec 31, today</td></tr></tbody></table>

The more of these you include, the more precisely the agent can scope and execute the query. Missing elements may trigger a clarification question.

##

## Writing Effective Prompts<br>

### **Be specific about what you want to measure**

The agent maps for example measurement terms to concrete attributes in the database. \
Using the right vocabulary reduces the risk of ambiguity and disambiguation steps.

| ❌ Less Effective                   | ✅ More Effective                                                                        |
| ---------------------------------- | --------------------------------------------------------------------------------------- |
| Show me the data for the building. | Show me the current temperature readings for all assets on the 3rd floor of Building A. |
| Any issues with the sensors?       | Which sensors on the 2nd floor haven't reported data in the last 48 hours?              |

***

### **Reference specific entities when you know them**

Mentioning asset names, asset types, or exact locations allows the agent to resolve scope without requiring clarification.

The more specific you are the faster responses will be, as the Assistant does not have to do vague searches first.

| ❌ Less Effective      | ✅ More Effective                                                                                |
| --------------------- | ----------------------------------------------------------------------------------------------- |
| Which rooms are warm? | Which RoomController assets on the 2nd floor are recording temperatures above 24°C?             |
| Check the sockets.    | Retrieve the current power consumption of all assets with asset type SmartSocket in Building A. |

***

### **Include a time range for historical queries**

Time ranges are important for trend queries. Without one, the agent may request clarification or apply a short default window.

| ❌ Less Effective                             | ✅ More Effective                                                            |
| -------------------------------------------- | --------------------------------------------------------------------------- |
| Show me energy consumption for Building B2F. | Show me the total energy consumption for Building B2F for the past quarter. |
| When was occupancy highest?                  | What was the peak daily occupancy in Building A during the last quarter?    |

{% hint style="info" %}
Larger Time Ranges for historical data will slow down Database Queries and subsequent Result Analysis
{% endhint %}

***

### **Ask one clear question at a time**

\
The agent retains context across a conversation. Splitting a complex request into a sequence of focused follow-ups produces more reliable results than combining everything into a single prompt.

| ❌ Less Effective                                                                        | ✅ More Effective                                                                                                       |
| --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Show me energy, occupancy, temperature, and alarms for all buildings for the last year. | Show me total energy consumption per building for the last quarter. → then: Now show me occupancy for the same period. |

## **Positive vs. Negative Prompt Examples**

| ❌ Less Effective                                                                 | ✅ More Effective                                                                             | Why                                                                      |
| -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| *"Which buildings have the biggest utilization gap versus energy intensity?"*    | *"What is the average energy consumption per building for the last month?"*                  | "Utilization gap" and "energy intensity" are not directly mapped metrics |
| *"Which sites show the highest opportunity for improvement?"*                    | *"Which buildings consumed the most energy in the last quarter? Rank them."*                 | "Opportunity" requires a defined metric to rank against                  |
| *"Where do space, asset, and energy KPIs point to the biggest business impact?"* | *"Show me average CO₂ levels and occupancy side by side for all meeting rooms."*             | Multiple undefined KPIs without a target metric                          |
| *"Are there anomalies?"*                                                         | *"Are there any assets in the server room that recorded temperatures above 80°C last week?"* | No metric, scope, or threshold defined                                   |
| *"Show me everything."*                                                          | *"Show me the current occupancy readings for all rooms in Building A."*                      | No scope or metric                                                       |

The less-effective examples fail not because the question is unreasonable, but because they lack a defined metric, scope, or time range that the agent can translate into a database query.

### **Tips & Patterns**

**Use asset type names when you know them** Referencing known asset types (e.g. `SmartSocket`, `EnergyMeter`, `RoomController`) makes scope resolution immediate and avoids disambiguation steps.

**Provide units when relevant** Adding *"in kWh"* or *"in °C"* helps the agent select the correct measurement attribute when multiple options exist.

**Follow the suggested prompts** Every response ends with grounded follow-up suggestions based on the data just retrieved. These are the fastest way to drill down progressively. You can also select them and then tune those to your specific needs.

**Iterate rather than over-specify upfront** A broad first question followed by focused follow-ups is more reliable than a single highly complex query.

**Use the tool call trace when results look unexpected** If a response does not match what you expected, expand the tool call trace. It shows exactly which assets and measurements were resolved, and where any ambiguity was encountered. Rephrasing with more specific terms usually resolves the issue.

### Common Pitfalls

| Pitfall                                              | What happens                                                                | How to fix                                                                                                   |
| ---------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Using business terms with no direct database mapping | The agent asks for clarification or selects the closest available attribute | Use specific terms that exists as attributes on your assets e.g. *"people-count"* instead of *"utilization"* |
| Omitting a time range in historical queries          | The agent asks for clarification or applies a short default window          | Always specify: *"last 7 days"*, *"past quarter"*, *"previous 2 months"*                                     |
| Asking multiple unrelated questions in one prompt    | Results may be incomplete or one question may be deprioritized              | Split into follow-up prompts or different conversations                                                      |
| Using an ambiguous location name                     | Multiple candidates may match; the agent asks you to choose                 | Provide more specific identifiers when available (e.g. concrete asset names, types or ids)                   |
| Expecting the agent to draw business conclusions     | The agent retrieves and surfaces data; interpretation is mostly up to you   | Use the results as input for your own analysis                                                               |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.buildings.ability.abb/collection/suites/space-and-assets-analytics/copilot-assistant/prompting-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.