Prompt Best Practices

General Best Practices

Write a Clear System Message

Set the role, tone, and boundaries in the system message. Even a single sentence makes a difference. Think of the model as a brilliant new hire who has zero context about your project.

Be Specific, Not Vague

• Say what you want, not what you don't want. "Write in plain prose paragraphs" beats "Don't use markdown."
• Use numbered steps for sequential processes, bullet points for unordered requirements.
• Specify output format, length, and audience explicitly.

Use Few-Shot Examples

Including 3-5 examples of the desired input/output is one of the most impactful techniques across all providers. Make examples relevant, diverse (cover edge cases), and structurally consistent.

Encourage Reasoning

For complex tasks, ask the model to reason before answering. "Think step by step" or "Evaluate the options before choosing" improves accuracy on problems that require multi-step reasoning.

Define the Output Format

Tell the model exactly what shape the response should take: JSON, bullet list, table, code block, or prose. If you don't want markdown, don't use markdown in your own prompt either.

Choose the Right Temperature

Test and Iterate

Prompt engineering is empirical. Build test cases with real data, establish a baseline, and iterate. Use the Playground to experiment quickly and the Eval system to measure changes.

Common Mistakes to Avoid

• Vagueness — "Summarize this" without specifying length, format, or audience.
• Overloading — Cramming multiple unrelated tasks into a single prompt. Break them up.
• Skipping examples — Not providing few-shot examples when format precision matters.
• No verification — Treating AI output as correct without a validation step.

PDK Best Practices

Structure with Roles

Use [#ROLE system], [#ROLE user], and [#ROLE assistant] to separate concerns. Put stable instructions in system, variable context in user.

[#ROLE system]
You are a customer support agent for {{company}}.
Always be polite and concise.
[END ROLE]

[#ROLE user]
Customer tier: {{customer.tier}}
Issue: {{issue}}
[END ROLE]

Use Typed Variables

Give variables a type and a default value so they never render empty. This prevents confusing instructions from reaching the LLM.

{{language:text ?? "English"}}
{{max_items:number ?? "5"}}
{{verbose:boolean ?? "false"}}

Keep Conditionals Simple

Use [#IF] to include or exclude entire instruction blocks based on context. This reduces token usage since only matching sections are sent to the LLM.

[#IF {{customer.tier}} #equals(Premium)]
This is a Premium customer. Offer priority handling.
[ELSE]
Follow standard support procedures.
[END IF]

Reuse with Sections

Extract repeated instruction blocks into [#SECTION] blocks and reference them with [#INCLUDE]. This keeps prompts DRY and makes updates easier.

[#SECTION name="tone_guidelines"]
Respond in a professional but friendly tone.
Use simple language. Avoid jargon.
[END SECTION]

[#ROLE system]
You are a support agent.
[#INCLUDE tone_guidelines]
[END ROLE]

Configure Meta for Each Prompt

Set model, temperature, and max tokens in the Meta tab so the prompt is self-contained and reproducible. Use meta conditionals to switch models based on task complexity.

provider: openai
model: gpt-4o
temperature: 0.3
maxTokens: 1024

Define Tools Alongside the Prompt

When your prompt needs function calling, define tools in the Tools tab. This keeps tool definitions versioned and tested alongside the prompt text.

Test with Real Variables

Always test with realistic variable values in the Playground. Edge cases — empty strings, very long text, special characters — often reveal problems that clean test data hides. Use the Eval system to automate this.