Crafting effective system prompts

​

System prompts vs. user prompts

​

The CARE framework

​

System prompt best practices

Define the Role

Clearly specify what the model is expected to do in its interactions. This focuses the model’s behavior, ensuring that it generates relevant responses and reduces the likelihood of unclear or off-topic responses.

Set the Tone and Style

Choose a tone that matches the context—technical, conversational, or professional—so the model’s replies align with audience expectations.

Clarify Output Format

Specify how the model should present its responses. Make it clear whether you want concise summaries, detailed explanations, or step-by-step instructions.

Set Constraints and Boundaries

Constraints and boundaries both limit model behavior, but they serve different purposes:

• Boundaries define topics or content the model should avoid entirely. Use boundaries to prevent the model from discussing sensitive information, providing professional advice outside its scope, or engaging with inappropriate requests.
• Constraints define requirements for how the model responds. Use constraints to control response length, formatting, terminology, or level of detail.

Provide Examples

When you need consistent formatting or a specific style, include an example of the preferred output in your system prompt. Examples help the model understand expectations more precisely than instructions alone.

Without an example:

When users report errors, provide a structured response that explains the issue and suggests a fix.

With an example:

When users report errors, structure your response as follows:

**Error:** [Brief description]
**Cause:** [Why this happens]
**Fix:** [Step-by-step solution]

Example:
**Error:** ModuleNotFoundError for 'pandas'
**Cause:** The pandas library is not installed in your environment.
**Fix:** Run `conda install pandas` or `pip install pandas` to install the package.

Use Delimiters

Delimiters help separate different parts of your prompt, making it easier for the model to distinguish instructions from reference content or examples. Common delimiters include ###, ---, and """.

Delimiters are especially useful when your system prompt includes templates, sample content, or multiple distinct sections.

Convert the following notes into structured documentation.

###
[User's notes go here]
###

Format with a brief summary followed by numbered steps.

Account for Ambiguous Situations

Provide clear fallback instructions for handling unclear or incomplete input. When the model encounters ambiguous user input, direct it to ask clarifying questions or suggest alternative options based on the information it has. This guidance helps keep interactions smooth and ensures the model provides useful responses even when input is unclear.

Guide Tool Usage

If the model has access to tools, such as Python tools, MCP servers, or plugins in Agent Studio, the system prompt is the primary way to control when and how the model uses them. Include guidance on:

• When to use each tool: Which tool to reach for in which situation, especially when multiple tools could apply.
• Tool ordering: Whether the model should try one tool before falling back to another.
• How to present tool results: Whether the model should summarize tool output, show it verbatim, or combine results from multiple tools.
• What to do when a tool fails: Whether to retry, try an alternative, or ask the user for help.

​

Iterative refinement

​

Documenting your prompts

PROMPT NAME: [Descriptive name for the prompt]
PURPOSE: [Scenario or use case this prompt addresses]
PROMPT TEXT:
[The full system prompt]

NOTES:
- [Tips for best results]
- [Known limitations or edge cases]

LAST UPDATED: [Date]

​

Examples

You are a data analyst who helps users explore and understand their data.

When answering questions about data, first use the database query tool. Write clear SQL queries and prefer existing views and tables over ad-hoc joins.

When a question needs custom logic, such as statistical analysis, modeling, or custom visualizations, move the work into a Jupyter notebook. Create or open a notebook, run cells incrementally, and explain each step.

Always:
- State which tool you are using and why.
- Show the query or notebook cell you executed.
- Summarize findings in plain language and call out caveats.
- Ask one clarifying question when the request is ambiguous before running anything.

You are a coding assistant that helps users write, debug, and optimize Python code.

**Role:** Provide clear, step-by-step explanations and working code examples. Follow Python best practices and prioritize efficient solutions.

**Tone:** Professional and supportive. Avoid jargon unless necessary, and define technical terms when you use them.

**Format:** Structure responses as follows when troubleshooting errors:
- **Issue:** [What went wrong]
- **Explanation:** [Why it happened]
- **Solution:** [How to fix it, with code if applicable]

**Boundaries:** Do not provide or reference sensitive information such as API keys, passwords, or user data. Do not offer advice outside Python development.

**Ambiguity:** If the user's input is unclear, ask one or two clarifying questions before proceeding.