> 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/copilot-assistant/improving-results/prompting-guide.md). # Prompting Guide This page explains how the Data Agent interprets requests and how to write prompts that return precise, useful results The way you phrase a question affects how precisely Copilot Assistant can resolve the request. Include the scope, metric, and time range when they are relevant. For the data behind those concepts, see [Data Requirements](/collection/copilot-assistant/improving-results/data-requirements.md). ## How Copilot Assistant Interprets a Request Copilot Assistant looks for concepts such as: | Element | Examples | | ------------------------- | ----------------------------------------------------------------- | | **Locations** | building, floor, room, zone, east wing, basement | | **Assets or asset types** | sensors, meters, SmartSocket, EnergyMeter, rooms | | **Metrics** | temperature, energy usage, occupancy, CO₂, water consumption | | **Time ranges** | last week, past quarter, between January 1 and December 31, today | The more of these elements you include, the more precisely the request can be scoped. Missing elements can trigger a clarification question. ## Write Effective Prompts ### Be Specific About What You Want to Measure Use vocabulary that maps to attributes in the asset model. 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 third floor of Building A. | | Are there any issues with the sensors? | Which sensors on the second floor have not reported data in the last 48 hours? | ### Name Known Entities Mention asset names, asset types, or exact locations when you know them. This reduces ambiguity and can make the response faster. | ❌ Less Effective | ✅ More Effective | | --------------------- | ------------------------------------------------------------------------------------------------- | | Which rooms are warm? | Which `RoomController` assets on the second 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, Copilot Assistant may ask for 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 can slow down database queries and subsequent result analysis. {% endhint %} ### Ask One Clear Question at a Time Copilot Assistant retains context across a conversation. Split a complex request into focused follow-ups instead of combining unrelated metrics and periods in one 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 ask a follow-up about occupancy for the same period. | ## Define Business Terms Business terms are useful only when they have a clear mapping to the asset model. Terms such as *utilization gap*, *opportunity*, or *energy intensity* need a defined metric and scope before Copilot Assistant can rank or compare them reliably. Instead of asking *"Which sites show the highest opportunity for improvement?"*, ask *"Which buildings consumed the most energy in the last quarter? Rank them."* Instead of asking *"Are there anomalies?"*, ask *"Are there assets in the server room that recorded temperatures above 80 °C last week?"* ## Useful Patterns * Use exact asset type names when you know them. * Provide units such as `kWh` or `°C` when multiple attributes could match. * Follow the suggested prompts to drill down into a result. * Start broad when exploring an unfamiliar portfolio, then narrow the scope. * Expand the tool call trace when a result looks unexpected. It shows which assets and measurements were resolved. ## Common Pitfalls | Pitfall | What can happen | How to improve the request | | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | A business term has no direct mapping | Copilot Assistant asks for clarification or selects the closest available attribute. | Use the attribute or measurement vocabulary defined in the asset model. | | A historical request has no time range | Copilot Assistant asks for clarification or applies a short default window. | Specify a period such as `last 7 days`, `past quarter`, or `previous 2 months`. | | Several unrelated questions are combined | Results can be incomplete or one request can be deprioritized. | Split the request into follow-up prompts. | | A location name is ambiguous | Multiple entities can match and Copilot Assistant asks you to choose. | Provide an asset name, type, or other concrete identifier. | | A business conclusion is expected from raw data | Copilot Assistant retrieves and surfaces data, but the business interpretation may remain undefined. | State the metric, comparison, baseline, or decision rule you want to apply. | --- # 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.buildings.ability.abb/collection/copilot-assistant/improving-results/prompting-guide.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.