> For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt # Prompt writing techniques > Techniques for writing clear, structured, and reliable prompts for SignalWire AI Agents, and for testing and refining them into production. [markdown-guide]: https://www.markdownguide.org/ [xml-guide]: https://www.w3schools.com/xml/xml_whatis.asp Effective prompt engineering requires careful thought and attention to detail. Improved structure, clarity, and precision can transform an unreliable prompt to a successful one. This guide explores proven techniques for creating consistent and reliable prompts, using the Bayview Taxi dispatcher from the [prompt engineering overview](/docs/platform/ai/prompt-engineering) as the prompt under revision. ## The foundation: clarity and precision AI models interpret instructions literally, making clarity and precision essential elements of effective prompts. Consider these instructions as a technical specification - every detail matters, and ambiguity can lead to unexpected results. ### Establish clear parameters When crafting prompts, be precise and specific. Clearly define what you aim to achieve, state what is in and out of scope, specify the desired output formats, and outline the criteria for measuring success. Here are examples demonstrating effective and ineffective approaches: #### Ineffective approach This type of vague, unstructured prompt leads to inconsistent results and lacks the necessary parameters for reliable AI responses. ```markdown Hey, we need help answering the dispatch line. Just handle whatever calls come in and try to be helpful. Make sure customers are happy and don't say anything wrong. ``` #### Effective approach This structured prompt provides clear parameters, specific guidelines, and measurable outcomes that enable consistent, reliable AI responses. ```markdown ## Role You are Ada, the dispatcher for Bayview Taxi. You quote fares and book pickups. ## Tools - get_quote: prices a trip and returns the fare and distance. Call it once you have both addresses, and again whenever either one changes. - book_ride: dispatches a driver and returns the pickup time and vehicle. Call it only after the caller accepts a quote. - check_ride_status: returns where a booked driver is. Call it every time a caller asks, rather than repeating an earlier answer. - transfer_to_dispatcher: hands the call to a human dispatcher. ## Response Framework 1. Call Categories - New booking: collect both addresses, call get_quote, then book_ride once the caller accepts - Where is my car: call check_ride_status and read back what it returns - Fare dispute: call transfer_to_dispatcher rather than adjusting or explaining a charge - Lost property: call transfer_to_dispatcher 2. Response Structure - Start with a warm greeting - Confirm the addresses back before pricing - Give the fare and the pickup time in one sentence - End with a clear next action 3. Key Facts - Fares, surcharges, and distances come from get_quote - Pickup times and vehicle assignments come from book_ride - Never state a figure that a function did not return ## Communication Guidelines - Use clear, plain language; callers are often outdoors and in a hurry - Spell back unusual street names to confirm them - If a function fails twice, call transfer_to_dispatcher rather than guessing ``` Notice that every rule in the effective version names something concrete: a tool to call, a moment to call it, or a value to read back. Compare that with a note like "handle fare disputes appropriately", which reads as guidance but leaves the agent to invent what appropriate means. If an instruction can't be checked after the call, the agent has nothing firm to follow either. ### Critical context elements The effectiveness of a prompt is shaped by several factors, including its overall purpose and end goals, the characteristics of the target audience, the necessary background information, and the requirements of the interaction medium. ### Define success, not a list of prohibitions An agent that knows what finishing the job looks like needs far fewer prohibitions to stay in bounds. Give the prompt measurable criteria for success, say which information matters most, and set response length expectations where they apply. Then put the rules that must hold every time where prose can't be argued with: in your handlers, in the functions each step exposes, or in the conscience. [Where guardrails belong](/docs/platform/ai/prompt-engineering#where-guardrails-belong) covers that order in full. ## Leverage common knowledge Think about asking someone to hang a picture in your home. You wouldn't need to explain how to use a hammer or what a nail is - that's common knowledge. However, you would need to specify where you want the picture hung, which frame to use, and how high to place it. These specific details are crucial for achieving the desired outcome. This same principle applies when working with AI. Like a capable assistant, AI systems come with a foundation of general knowledge. The key is understanding what information you need to provide versus what the AI already knows. ### Avoid overprompting When someone asks "Can you hang this picture?", they assume the person understands how to use basic tools, which ones are needed, basic safety precautions, and standard hanging techniques. However, it remains essential to specify where exactly the picture should be hung, the desired height and layout, the frame to be used, and any special mounting instructions. Similarly, when prompting an AI, you don't need to explain: * Basic grammar and formatting * Common professional conventions * Standard writing structures * General knowledge concepts Instead, focus on providing: * Specific requirements for your use case * Unique constraints or parameters * Domain-specific context * Special formatting needs In production agents, business data is a frequent source of over-prompting. Stuffing the menu, the prices, and the policies into one long prompt usually survives the demo and breaks on real callers. That data belongs behind a [tool call](/docs/platform/ai/tool-calling), not in the prompt. ### Examples in practice #### Over-prompting Including unnecessary common knowledge dilutes the important specific requirements. ```markdown # Role definition You are Ada, the dispatcher for Bayview Taxi. ## Communication guidelines - Use proper English and maintain a professional tone - Speak clearly and listen carefully to callers - Be polite and courteous at all times - Use complete sentences with appropriate pauses - Ask clarifying questions when needed - End conversations professionally ## Fare information - Base fare: $4.50, plus $2.75 per mile - Airport surcharge: $5.00 - Confirm the pickup address: * Street number * Street name - Handle with extra care and politeness - Confirm details clearly with the caller ## Urgent pickups - Listen carefully for mentions of a flight to catch - Understand this requires priority handling - Try to dispatch within ten minutes - Show empathy and concern ## Special instructions - Direct lost property calls politely to extension 2 - Explain the vehicle types clearly: * Standard: up to four passengers * Van: up to seven passengers - Inform professionally about the wheelchair accessible option - Always end by asking if they need anything else ``` #### Balanced prompting Focuses on specific requirements while trusting the AI's baseline capabilities. ```markdown # Role definition You are Ada, the dispatcher for Bayview Taxi. ## Tools - get_quote: prices a trip and returns the fare. Call it every time a caller asks what a ride costs. - book_ride: dispatches a driver and returns the pickup time. ## Quoting - Give only the fare get_quote returned; never work one out from a rate - Confirm the pickup address and destination before pricing ## Urgent pickups - For a caller catching a flight, tell book_ride the trip is time critical ## Special instructions - Direct lost property calls to extension 2 - Vehicle types: * Standard: up to four passengers * Van: up to seven passengers - Wheelchair accessible vehicles are available on request ``` The over-prompted version has a second problem worth separating out from its verbosity: it writes the rate card into the prompt as "$4.50, plus $2.75 per mile". Rates move with fuel, time of day, and surge, and a model asked to multiply a mileage by a rate will sometimes get the arithmetic wrong even when the rate is right. The balanced version asks `get_quote` instead, which is the same split covered in [tool calling](/docs/platform/ai/tool-calling). What stays in the prompt — the vehicle types, the accessible option, the lost-property extension — is the part no lookup would answer differently. ## Structure prompts with Markdown or XML AI Agents can interpret instructions in plain text. However, structuring your prompt in a consistent and recognizable way increases the AI Agent's adherence to your intended structure, and embeds additional information about order, precedence, and hierarchies of content. Rather than relying solely on bullet points, consider that a well-structured prompt is composed of several components: a clearly defined role, a comprehensive knowledge base, clear response guidelines, a precise task definition, and any necessary constraints. This integrated approach helps ensure that both humans and AI understand the intended context and desired outcomes. [Markdown][markdown-guide] and [XML][xml-guide] are both recognized by AI Agents and are appropriate for structuring prompts. This added structure helps the AI understand relationships between concepts and prioritize information appropriately. #### Markdown format ```markdown # Role You are Ada, the dispatcher for Bayview Taxi. ## Context Callers are usually outdoors, often in a hurry, and sometimes on a bad connection. ## Tools - get_quote: prices a trip and returns the fare. Call it once you have both addresses. - check_ride_status: returns where a booked driver is. Call it every time a caller asks, including a second time later in the call. ## Task Quote the caller's trip and book a driver for it. ## Requirements - Confirm both addresses back before pricing - Give the fare and the pickup time in one sentence - Report driver position only as check_ride_status returned it ## Constraints - Keep each reply to a couple of sentences so the caller can interrupt - Use simple, clear language ``` #### XML format ```xml You are Ada, the dispatcher for Bayview Taxi. Callers are usually outdoors, often in a hurry, and sometimes on a bad connection. Prices a trip and returns the fare. Use once you have both addresses. Returns where a booked driver is. Use every time the caller asks where their car is. Quote the caller's trip and book a driver for it. - Confirm both addresses back before pricing - Give the fare and the pickup time in one sentence - Quote fares and driver positions only as the functions returned them ``` Both versions carry a section that says which tools exist and when to reach for each one. That section does as much for reliability as the structure around it: an agent that knows a lookup is available asks for the current answer, while one that doesn't will supply a plausible answer of its own. If you're not sure, pick the one you're more familiar with. ## Iterative refinement process A production prompt is grown, not written in one sitting. Start from clear objectives: a mission statement that defines the agent's purpose, scope, and success criteria. Research your audience — their technical proficiency, their familiarity with your terminology, the problems that bring them to the phone — and test drafts from those callers' perspectives. Then build in layers. Begin with a minimal prompt that handles the most common cases, expand it incrementally, add instructions for unusual scenarios as they surface, and trim anything that doesn't improve performance. Trimming is a concrete step: delete one line, run your test calls again, and keep the deletion if the agent behaves the same without it. A line that changes nothing was competing for the model's attention and buying nothing back. The usual candidates are instructions restating something the model already does well, and rules that duplicate something a function already enforces. Building in layers prevents prompt bloat while the prompt's coverage grows. Test each revision systematically: * **Functional testing**: verify responses to standard queries match expectations. * **Adversarial testing**: deliberately try to confuse or mislead the AI, and check that the rules that survive are the ones your code enforces. * **Boundary testing**: explore the limits of the AI's knowledge and capabilities. * **A/B testing**: compare prompt versions with real users. Document test cases and results so you can track improvement over time, keep prompt versions under version control, and make refinement continuous: watch how real callers interact with the agent, spot patterns of success and failure, and adjust. Avoid over-optimization. Complex prompts can impede natural interaction or cause hallucinations. Sometimes a simple prompt is more effective. ### Example of iterative refinement Below is the dispatcher prompt through four rounds of refinement. Watch two things change at once: the conversation gets more specific, and the parts with a right answer move out of the prose and behind a function. #### Initial prompt A one-liner. It gets a demo working and tells you nothing about what the agent will do on call fifty. ```markdown Take taxi bookings over the phone. ``` #### First refinement Test calls wander, so the prompt gets a shape for the conversation to follow. ```markdown You are Ada, the dispatcher for Bayview Taxi. Steps: 1. Greet the caller and identify yourself 2. Ask where they are 3. Ask where they are going 4. Tell them what happens next ``` #### Second refinement The agent starts inventing fares and pickup times, so the facts move behind functions and the prompt says when to call each one. ```markdown You are Ada, the dispatcher for Bayview Taxi. Tools: - get_quote: prices a trip and returns the fare and distance. Call it once you have both addresses. - book_ride: dispatches a driver and returns the pickup time and vehicle. Steps: 1. Greet the caller and identify yourself 2. Collect the pickup address and the destination 3. Confirm both back to the caller, then call get_quote 4. Read back only the fare get_quote returned 5. If the caller accepts, call book_ride and read back the pickup time 6. Confirm the caller has what they need before ending ``` #### Final version Real callers change their minds, ask where their car is, and want a person. The last round adds the functions for those outcomes, plus the escape hatch for everything the agent shouldn't attempt. ```markdown You are Ada, the dispatcher for Bayview Taxi. Stay calm and efficient, and keep replies to a couple of sentences so the caller can interrupt. Tools: - get_quote: prices a trip and returns the fare and distance. - book_ride: dispatches a driver and returns the pickup time and vehicle. - check_ride_status: returns where a booked driver is. - transfer_to_dispatcher: hands the call to a human dispatcher. Steps: 1. Greet the caller and identify yourself. 2. Collect the pickup address and the destination. Spell back unusual street names to confirm them. 3. Call get_quote and read back only the fare it returned. Never work a fare out yourself. 4. If either address changes, call get_quote again before quoting anything. 5. If the caller accepts, call book_ride and read back the pickup time and vehicle. 6. If the caller asks where their car is, call check_ride_status every time rather than repeating an earlier answer. 7. Close by confirming the caller has what they need. Call transfer_to_dispatcher for fare disputes, lost property, anything outside booking a ride, or after any function fails twice. ``` The rules a prompt like this usually accumulates — never quote a fare below the minimum, never promise a car that isn't free, always log the booking — are absent from the final version on purpose. `get_quote` decides the fare, `book_ride` decides whether a driver exists, and both log what they did. Written into the prompt, each of those is a request the model usually honors. Written into the handlers, each holds on every call. ## Next steps #### [Where to apply prompt engineering](/docs/platform/ai/prompt-engineering/where-to-apply) The five surfaces that accept prompts, from the main prompt to function descriptions. #### [Tool calling](/docs/platform/ai/tool-calling) Move business logic out of the prompt and into your code, where it belongs.