Best Practices: Writing Effective Agent Instructions
Learn how to write effective agent instructions for Medallia Insights Assistant
The out-of-the-box system instructions are heavily optimized. When customizing, use these prompt engineering principles to ensure accurate, safe, and highly performant agent behaviors:
Core Writing Principles
Be Direct and Concise — State exactly what you want the agent to do. Eliminate conversational filler, explanations, or meta-commentary.
Keep Instructions Atomic — Target one specific behavior, metric, or formatting rule per sentence. Avoid compounding multiple complex logical constraints into a single line.
Use Imperative Commands — Begin instructions with strong, absolute commands like "Always,""Never,""Include," or "Omit" to set firm logical guardrails.
Avoid Ambiguous and Optional Phrasing — Never write tentative words like "should,""might,""try to,""consider," or "generally." Also avoid subjective terms like "appropriate" or "reasonable."
Explicitly Identify Fields — To avoid data mapping errors, explicitly call out fields using the format:
<field_name> (<field_keyname>).Respect Safety Policies — Do not attempt to bypass core platform safety controls or inject instructions that compromise data governance. Automated LLM services scan and block invalid or malicious prompts at both the admin-saving stage and user-query runtime.
Instruction Use Case Library
Use these pre-tested structural templates to configure common business scenarios:
| Business Use Case | Target Goal / Behavior | Recommended Instruction Template |
|---|---|---|
| Defining Primary Metrics | Force the agent to prioritize a core business score. | "Always prioritize and utilize Net Promoter Score (nps_score) as the primary calculation metric when analyzing performance." |
| Excluding Irrelevant Fields | Omit confidential or misleading fields from analysis. | "Never include or utilize internal employee ID fields (emp_id) or test survey scores in your generated responses." |
| Sorting Qualitative Data | Establish clear priorities when listing customer issues. | "When analyzing Topics, always sort outputs by the most negative Impact Score. When answering queries about complaints or problems, list topics ordered from worst to best impact." |
| Formatting Output Structure | Standardize how insights are physically presented. | "Always structure customer recommendations as a bulleted list. Do not summarize customer suggestions into paragraph format." |
| Setting Response Length | Force brevity and keep answers concise. | "Limit all responses to 3 paragraphs or fewer when answering questions." |
| Enforcing Operational Guardrails | Block operational roles from receiving tactical recommendations. | "Never provide suggestions, advice, or recommended next steps when answering questions for Frontline Manager roles." |
