Before jumping into Custom Instruction best practices, let’s cover the definition and a few examples.
What are Custom Instructions?
Custom Instructions enable Author Pros to curate Q&A responses to questions by adding domain-specific knowledge that can’t be captured through a topic’s metadata settings, such as synonyms or semantic types. By providing these metadata descriptions or custom instructions, Author Pros can guide Amazon Q to align its responses with distinct definitions, preferences, and expert knowledge—ensuring more accurate, relevant, and tailored answers that are better suited for their business needs.
Custom Instruction Examples
Defining Corporate Fiscal Year
In the below example, the custom instruction our fiscal year starts on April 1st tells Q how to answer proportion of foreign transactions in FY 2024.
Defining Ambiguous Language
This NYC 311 Incident Reports dataset from NYC Open Data contains anonymized records of non-emergency complaints submitted by the public, including complaint type, location, responsible agency, and resolution status. For example, someone asks a vague “Who” question, Who handles the most complaints relating to noise. The data might contain multiple fields that can map to “Who”: Agency, Case Manager, or Technician. The topic author can add a custom instruction to guide Q based on the end user’s preferences: "Who" typically refer to the Agency Name, not the Case Manager or Technician.
Using Latitude and Longitude for Map Visuals
To use latitude and longitude to plot points on a map visual, you can add an instruction like whenever a user asks for a map, include latitude and longitude in the answer. This gives Q a signal to use lat and long, instead of other geo-attributes like zip or city.
Best practices for writing custom instructions
Match cell values precisely
- Use the exact cell value from the database, including casing and formatting.
- If the value is ambiguous, reference its source column to clarify.
Examples:
- Instead of: "AMZ are Amazon customers"Use: “AMZ are ‘Amazon.com, Inc.’ customers”
- Instead of: "ETPs are enterprise customers"Use: “ETPs are customers from the enterprise Segment”
Be specific and quantitative
Avoid vague language—be clear about filters, thresholds, and source columns.
Example:
- Instead of: "Filter large customers when talking about sales
- Use: “Filter customers where Annual Revenue > $1M when talking about sales”
Use formatting for clarity, not function
Spacing and line breaks do not affect model behavior, but help authors read and maintain instructions more easily.
Understand what custom instructions cannot do
Custom instructions improve Amazon Q’s understanding of your business context, but they do not add new capabilities. These instructions will not:
- Change chart type selections
- Perform calculations or fill nulls
- Create new fields
- Control formatting, colors, or legends
- Alter the narrative or number/type of visuals
Metadata Types
Use the following table to understand when and how to apply different types of metadata to improve Q&A answer accuracy. Each metadata type plays a unique role in clarifying context, resolving ambiguity, and ensuring that answers are aligned with business rules or domain-specific terminology.
| Metadata Type | When to Use | How it Improves Answer Accuracy |
|---|---|---|
| Field-Level Description | When the Q&A system needs to understand ambiguous or domain-specific column names (for example, DTC Spend). |
Clarifies field semantics so the model can answer more precisely (for example, interpreting DTC Spend as Direct-to-Consumer marketing expense). |
| Topic-Level Description | When users may ask broad or ambiguous questions and Amazon Q needs more context about the topic’s overall purpose (for example, sales performance vs. clinical trial data). | Helps disambiguate general terms and steer answers toward the right domain (for example, sales vs. marketing). |
| Dataset Description | When users have access to multiple datasets and the Q&A system needs to identify which one best fits the question. | Enables dataset selection logic by providing context about each dataset’s purpose and content. |
| Topic-Level Custom Instructions | When a topic has specific business rules, timeframes, or definitions (for example, fiscal year ≢ calendar year). | Applies custom logic or definitions (for example, defining Q1 as August-October) to tailor answers appropriately. |
Update via UpdateTopic API
Authorized users can update CustomInstructions via UpdateTopic API.
Read the complete documentation here.