Writing good prompts and instructions

A capable employee still needs to know which job they have been hired to do. “Be helpful” does not tell a support adviser whether they may approve refunds, change an account, or promise delivery dates. An agent has the same need for a clear job description, although it also requires software controls that a written instruction cannot replace.

A prompt is the input given to a model for a particular response or task. It can include the user’s question and supporting context. System instructions are standing directions supplied by the application to define the agent’s role and behaviour across requests. Think of the user’s message as today’s assignment and the system instructions as the job description and working rules.

Describe the job before choosing the wording #

Start with the work the agent should accomplish, not a personality. “You are a brilliant assistant” says little about a useful result. “Help customers understand delivery options using the current policy, and use the order-status tool for questions about a specific shipment” names a purpose and connects different questions to appropriate evidence.

Be explicit about the intended audience. A support answer for a customer should not read like an internal incident report. An internal assistant may use terminology employees recognise, while a public assistant should explain unfamiliar terms. Defining the audience helps the agent choose detail and tone without pretending that style is the whole task.

Next, describe success in a way a reviewer can observe. For example: answer the customer’s question, distinguish policy from current status, cite the supporting source when available, and ask a necessary follow-up when evidence is missing. These criteria are more testable than “always deliver an excellent experience.”

The sections of a useful instruction #

A good instruction is usually a small, organised document rather than one long paragraph of demands. Keep rules about the same subject together. If several passages describe what to do when information is missing, combine them into one clear rule instead of making the agent reconcile slightly different versions.

The sections should agree. “Never ask a question” conflicts with “verify all required details before updating a record” whenever the user omits a detail. “Always answer confidently” conflicts with admitting that a source is unavailable. Resolve such conflicts in the instruction itself; do not expect the model to discover the business priority you intended.

Replace vague adjectives with behaviours #

An instruction can be short without being vague. The test is whether two reviewers would recognise the same successful response. “Professional” means different things to different people. “Use plain language, avoid blame, and explain the next available step” points to visible behaviour.

The specific version does not guarantee correctness. It gives the application a clearer behavioural target and gives reviewers a basis for checking answers. Tool permissions, source quality, and identity checks still need to work independently. A written rule saying “only read this customer’s order” is not sufficient if the connected service exposes every order without checking access.

A second common problem is asking for an output without explaining how it will be used. A manager scanning a case summary needs different detail from an engineer investigating a failure. State the desired structure when it helps the reader or a downstream system use the result.

If software needs to read the result automatically, agree on the exact fields and validate the response in software. Human-friendly formatting and machine-readable output are related but different requirements. A heading that looks right to a person does not necessarily satisfy a program expecting a defined data structure.

Use examples to teach distinctions #

Examples help when a rule is easy to misunderstand. “Do not invent facts” is broad; a sample answer that admits a failed lookup demonstrates what honesty looks like during a real task. Include both ordinary cases and cases where the agent should ask, stop, or refer the user to someone else.

Keep examples consistent with the written rules. If the rules say a refund requires approval but every example grants one immediately, the instruction sends competing signals. Also make clear which details are fictional. Do not use real customer conversations containing personal information as public examples, and remove unnecessary identifying details from internal test material.

That distinction is important in many business tasks. “No record was found” differs from “the search failed.” “The request was submitted” differs from “the change was confirmed.” Useful instructions name these differences because plausible language can otherwise hide operational uncertainty.

Draft, test, and refine with real situations #

Do not judge an instruction only by reading it. Test how the configured agent behaves when a user is unclear, a source is missing, or a tool returns an error. Use representative conversations from the intended task, with appropriate permission and removal of identifying information. Invented scenarios can fill gaps, but should not be the only evidence of readiness.

Keep a versioned copy of instructions: a record of which wording was active and what changed. This makes it easier to explain why behaviour changed and to restore an earlier version if a revision causes problems. Small changes are usually easier to evaluate than replacing the entire instruction after one disappointing answer.

Avoid growing the document into a catalogue of every failure ever observed. Some rules belong in tools or application controls; others belong in a specialised skill loaded for that task. Repeated warnings can obscure the main job. The goal is a coherent working agreement, not the longest possible prompt.

Recognise the limits of wording #

Better instructions can improve consistency, but they cannot supply unavailable data, create permissions, or guarantee compliance. If an agent lacks a current policy, add the correct source. If a tool accepts unsafe actions, fix the integration. If the process requires human approval, enforce that checkpoint rather than adding stronger adjectives to the prompt.

For a deeper drafting framework, continue with Anatomy of a prompt. The common prompt mistakes unit examines conflicting rules, missing context, and other patterns that make behaviour harder to predict.

What’s next: begin Introduction to knowledge creation and learn how to prepare the evidence your instructions tell an agent to use.