Reliable AI agents need more than a capable model. They need clear instructions for choosing tools, planning work, requesting confirmation, handing off tasks, and recovering when an action fails. This guide provides a reusable checklist and practical AI agent prompt templates for building safer, more predictable multi-step workflows.
Overview
An AI agent prompt should define how the agent thinks about actions, not merely what the agent is expected to accomplish. A useful agent system prompt establishes the agent's role, available tools, permission boundaries, planning method, output format, and recovery behavior.
The most dependable design separates decisions into stages:
- Understand: identify the user's goal, constraints, missing information, and success criteria.
- Plan: break the task into observable steps and identify which steps require tools.
- Check permissions: distinguish between reading information, creating a draft, and taking an external or irreversible action.
- Act: call the smallest suitable tool with validated arguments.
- Verify: inspect the result and compare it with the requested outcome.
- Recover or hand off: retry safely, ask a focused question, or transfer the task with a useful state summary.
Use these stages as a design checklist rather than forcing every workflow into one rigid format. A research assistant may need source verification and evidence tracking, while a content workflow may need approval gates and structured drafts. For broader guidance, compare this approach with AI agent system prompt patterns for safety and reliable execution.
Checklist by scenario
1. Tool selection and safe calling
Tell the agent what each tool is for, when it must not be used, and what information it needs before a call. Tool descriptions should explain side effects in plain language. A search tool, for example, may be read-only, while a publishing or payment tool may create an external consequence.
Tool-use instructions:
- Select a tool only when it directly advances the user's stated goal.
- Prefer read-only tools for discovery and verification.
- Do not use a tool when required arguments are missing or ambiguous.
- Before any external, destructive, financial, or public action, summarize the action and request confirmation unless the user has explicitly granted permission for that exact action.
- Use the minimum permissions and minimum data needed.
- After each call, inspect the returned status and evidence before continuing.
- Never claim that an action succeeded unless the tool result confirms success.Pair these instructions with a tool-call contract. For each tool, document its purpose, required inputs, optional inputs, expected result, failure states, permission level, and whether confirmation is required. This contract is more dependable than relying on a vague instruction such as “use tools responsibly.”
2. Planning a multi-step task
Planning prompts should make the agent's next actions inspectable without demanding an unnecessary essay or exposing private reasoning. Ask for a short task plan containing objectives, dependencies, tool calls, checkpoints, and stopping conditions.
Planning template:
Before acting, produce a concise execution plan with:
1. The requested outcome.
2. Any assumptions that could change the result.
3. The ordered steps required.
4. The tools needed for each step.
5. A verification check after each consequential step.
6. The condition that ends the workflow.
If a missing detail blocks safe progress, ask one focused clarification question instead of guessing. Re-plan when a tool result changes the available options.For long workflows, limit the plan to the current objective and near-term steps. A large speculative plan becomes stale when a tool returns unexpected data. This is one reason prompt chaining can be useful: separate intake, planning, execution, and review into explicit stages with small, testable outputs.
3. Confirmation before consequential actions
Confirmation should be specific. The agent should identify what will happen, which account or destination is affected, what content will be sent or changed, and whether the action can be reversed.
Confirmation template:
The next step will [describe the exact action] using [account, destination, record, or environment].
It will [state the visible or irreversible effect].
I found [key inputs or proposed content].
Do you want me to proceed?
Do not treat a general request to complete a task as confirmation for a new, higher-impact action that was not clearly implied.For content operations, approval can be required before publishing, sending, deleting, or overwriting. For development workflows, use separate permissions for reading a repository, editing files, running tests, and deploying changes.
4. Handoffs between agents or people
A handoff should preserve the state needed to continue, not simply say that the task is unfinished. Require the agent to summarize the goal, completed steps, evidence, open questions, blocked actions, relevant artifacts, and recommended next step.
Handoff template:
- Goal:
- User constraints:
- Completed steps:
- Tool calls and confirmed results:
- Files, records, or sources involved:
- Current status:
- Blocking issue or unanswered question:
- Actions requiring approval:
- Recommended next step:
- Confidence or verification notes:Use a consistent handoff schema across agents. If the receiving agent cannot distinguish facts from assumptions, it may repeat work, make an unsafe guess, or report an unverified result as complete.
5. Error recovery and bounded retries
Recovery instructions should tell the agent how to classify an error before trying again. A temporary network failure may justify a limited retry; invalid arguments require correction; an authorization failure requires escalation or a permission change; and an uncertain result requires verification before repetition.
Recovery template:
When a tool fails:
1. Record the tool, inputs, error category, and whether the action may have partially succeeded.
2. Do not repeat a potentially consequential action until its status is verified.
3. If the error is a correctable input problem, revise only the invalid field.
4. If the error appears temporary, retry no more than [number] times with a changed or delayed request when appropriate.
5. If permission is missing, explain what access is needed and stop.
6. If the result remains uncertain, report the uncertainty and ask for guidance.
7. Update the plan after recovery rather than continuing from an invalid assumption.Recovery is also a user-experience feature. A concise explanation of what failed and what is needed next is more useful than a generic “something went wrong.”
What to double-check
Before deploying an agent prompt, review the tool-call contract and test the boundaries around it. Confirm the following:
- Scope: Is the agent's role narrow enough to make decisions consistently?
- Authority: Does the prompt distinguish observation, drafting, modification, publication, and deletion?
- Inputs: Are required arguments validated before a call?
- Privacy: Does the workflow avoid sending unnecessary personal, confidential, or irrelevant data to tools?
- Idempotence: Could a retry duplicate a message, record, purchase, or deployment?
- Verification: Does the agent check the actual result rather than infer success from an attempted call?
- Output: Is the handoff or final response structured for the next system or person?
- Stop conditions: Does the agent know when to pause, ask, escalate, or end?
If a downstream application consumes the result, use a defined schema and validate it in code. The structured output and JSON Schema guide can help when an agent must return predictable fields. Keep tool results, user instructions, and untrusted external content clearly separated; formatting guidance is available in the AI prompt formatting guide.
Common mistakes
- Giving the agent a broad mission without boundaries. “Handle everything” does not define authority, stopping points, or acceptable risk.
- Describing tools without side effects. The agent needs to know whether a call reads, changes, sends, publishes, or deletes data.
- Using confirmation as a vague afterthought. A confirmation request should name the exact action and its impact.
- Retrying automatically after every failure. Repetition can duplicate an action or conceal an authorization problem.
- Writing plans that are too detailed. Plans should adapt when new information appears; they are not a substitute for verification.
- Accepting tool output as truth. Check status fields, returned records, timestamps, and other available evidence.
- Testing only successful paths. Include missing inputs, malformed arguments, permission failures, empty results, timeouts, duplicate requests, and conflicting instructions.
Turn these failure modes into a prompt evaluation set. The prompt evaluation playbook provides a reusable way to record expected behavior, observed behavior, and regression results as the workflow changes.
When to revisit
Review an AI agent prompt whenever its tools, permissions, model, data sources, or user-facing responsibilities change. A prompt that worked for a read-only research assistant may not be safe after adding a publishing tool. Likewise, a new tool-call format or framework convention can change how arguments, refusals, errors, or structured outputs are handled.
At minimum, revisit the workflow before seasonal planning cycles, major content campaigns, new integrations, permission changes, or production releases. Run a small regression set that covers normal tasks, ambiguous requests, unsafe actions, failed tools, interrupted sessions, and handoffs. Compare behavior across the models your application supports rather than assuming a prompt will behave identically everywhere; the cross-model prompt portability guide offers a practical starting point.
Finish each review by updating three artifacts: the agent prompt, the tool-call contract, and the evaluation cases. Record the date, changed capability, expected behavior, and any known limitation. This creates a maintainable developer prompt library instead of a collection of forgotten instructions.
Action checklist: choose one agent workflow, list every tool and side effect, add a confirmation rule for consequential actions, define a bounded recovery path, create a structured handoff, and test at least one failure case for each tool. Then repeat the review whenever the workflow or its inputs change.
