How to Write Effective AI Instructions

AI instructions are the natural-language text an AI agent follows at run time: a workflow step's Directions, the instructions that implement a custom AI tool, and the directions a step follows when it does scheduled work. They are the biggest single lever you have over how reliably your thunk behaves.

This article has two parts. Concepts explains what the platform already does around your instructions, which tells you what is left for them to say. Details gives the guidelines for writing that part well. The same guidelines apply wherever an instruction lives: a step, a custom AI tool, or anywhere else an agent runs.

For the parts of a step's AI Instructions other than the text (properties, tools, examples, settings), see AI Instructions. To have existing instructions rewritten by these guidelines, see How to Improve AI Instructions with Rewrite.

When a step runs, the agent does not start from a blank page. Before it reads a word you wrote, the platform has already given it:

So your instructions only need to carry the logic of your workflow: what this step is for, the order the work happens in, and the business rules and decisions that are specific to you. Everything else is better expressed somewhere the platform can enforce it.

Instructions are read and interpreted. Properties, tools and step settings are applied exactly. A rule that can live in one of those places is more reliable there than in prose:

This applies to the results a step records as much as to its inputs. When a result has a known set of values (a category, a status, a priority, a set of flags or codes), give the property a fixed list of allowed values, including when the property holds a list of several values. The agent can then record only values from the list: it cannot misspell one or make one up, and the instructions no longer need to list the choices.

The reasoning behind this split is in AI reliability mechanisms.

Two more things about the run-time model shape how instructions should read:

Each guideline states a rule; most add the reason for it or a short example.

Start with a clear Objective statement, then describe the Process. The objective tells the agent what success looks like, so it can make sensible choices the process does not spell out.

Objective: Assess the vendor's security posture.
Process: 1. Read the vendor's questionnaire answers. 2. …

Write the process as a numbered list. An entry can have further detail as sub-items; make sub-items bulleted and indented. A numbered list reads as an order to follow; the same steps buried in a paragraph do not.

Present the instructions in the order the work happens: consume the inputs, then process, prepare or analyze them, then act on the result. Do not interleave these. Transform the data first, then give clean instructions on what to do with the transformed data — do not mix details of how to transform the data into the details of where to send it.

Describe actions in the imperative: "Extract the invoice total", "Send the summary to the requester". Avoid passive phrasing such as "the total should be extracted" or "it is recommended that".

State the condition first, then the action it governs: "If the invoice is overdue, send the reminder", not "Send the reminder only for overdue invoices". The agent reads in order, so an action that comes before its condition can be carried out before the agent reaches the words that limit it. Avoid "only do X for Y", "do X when Y" and "do X unless Y". A condition can also be set up in one sentence and branched on in the next: "Check whether the company is a good fit. If it is, mark Is Qualified as yes. If not, record why."

Describe an action by its logical intent ("send an email to the requester"), not by its mechanical implementation ("call the send-email tool"). Do not name tools in instructions. When the method matters, describe it by what it does ("look the shop up in a places directory") and choose the mechanism by enabling the right tools on the step, disabling the ones it should not use.

When the process deals with a set of items, write it as an explicit for-each instruction:

For each customer in Customers: a) collect their usage history, b) classify them as High or Low usage.

Never instruct the agent to run a loop one item at a time — the work is set-oriented and happens in batches. Leave out pseudo-code such as "keep this value in memory" or "add one to this counter for each item". "For each" says what happens to every item; it does not ask for a sequential loop.

Do not tell the agent to "store" or "persist" values into particular variables; recording results is implicit. It is fine to say which properties should be filled in — "record Title, Salary, and Age" — to make clear which outputs a part of the process produces.

Do not describe low-level API or tool-calling protocol: retries, HTTP error handling, parsing a response, or which field of a response to read ("read data.score from the JSON"). Say what should happen, not how the agent should invoke it: "get the applicant's credit score" is enough. Business rules are not mechanics: "if the invoice has no purchase-order number, record it as unmatched" belongs in the instructions; "if the API call fails, retry three times and then write the error into Notes" does not.

Describe spreadsheet work as lookup, append, update or upsert against a named sheet — never by row numbers, header parsing or moving between tabs. Those four operations are lookup (find matching rows), append (add a row), update (find a row by its key columns and change other columns), and upsert (update the row with this key, or add it if it is not there). Write instructions in those terms:

Never leave a bare "user" in instructions. Wherever the instructions ask someone for something or send something to someone, name the party: the end user who submitted the inputs, by their role ("the requester", "the submitter"), or the human service agent. Remember that the end user can only be reached through a conversation property or by email. Asking the human service agent for help usually stops the agent's processing until they answer; it does not finish the step.

If a step's logic runs past about 20 lines, it should almost certainly be broken up — either into sequential steps (linear decomposition) or by moving parts of it into tools (hierarchical decomposition). Be aggressive about the second: any sequence of deterministic logic belongs in a tool. See the two worked examples below.

Any arithmetic beyond something trivial belongs in a tool, and that includes date arithmetic — do not ask the agent to work out dates. Several instructions that each do some arithmetic can be combined into a single tool.

Do not validate inputs in the instructions ("if Region is not one of North America, Europe or Asia, stop with an error"). Remove such instructions, and put the constraint on the property's type instead. The instructions can then assume they are given valid data, or at least data that meets the property's constraints — without saying so: do not restate the allowed values, even as an assumption.

If a step should do something other than stop with an error when it runs out of time, say so as a condition. "If you run out of time, finish the step with what you have" and "If you run out of time, ask the requester how to proceed" are both clear. Without such an instruction, the agent stops the step with an error when its time is up. Vague pressure such as "work quickly" or "don't take too long" gives the agent nothing to act on when the limit is reached; leave it out.

A step's input is often a list in which every entry needs a lot of transformation and filtering, and then an action. You could write that as one for-each with all the logic nested inside it. It is better as two steps: the first takes the input list, transforms and filters it, and produces a transformed output list; the second takes that list and carries out the actions.

Take pieces of the logic and move them into tools. A tool is a way of scoping a concern, like a function call; it does not have to be deterministic or written in code — a custom AI tool written in English is still a tool. Logic that is plainly deterministic is the best candidate.

Keep tools coarse: many tiny tool calls are slow. You would not build a tool to add two numbers; you would build one that takes a list of entries, adds or updates them in a spreadsheet, and returns a summary of what changed. A tool can take a whole list, or handle one entry and be applied to every entry in a list — the agent calls it as one batch either way.

Move the physical details into the tool. Its inputs and outputs are logical, and its implementation holds the specifics: for a tool that writes to a spreadsheet, the column mapping and formatting live inside the tool, not in the step's instructions.

You do not have to write perfect instructions in one pass. Start with a plain description of the task, test the step on real work items, and tighten the instructions wherever the agent went off course. The biggest improvement is usually specificity: say exactly what to do and, where the method matters, describe the method (and enable the tools that carry it out).

Cover the awkward cases, not just the happy path. Say what the agent should do when a value is absent, a document is incomplete, or the inputs disagree — for example, "if the invoice has no purchase-order number, record it as unmatched rather than guessing one." Being explicit stops the agent from filling a gap with a confident but wrong answer.

Many steps decide whether a person needs to take over — and record that decision as a property, such as Needs review set to Yes. Wording like "hand off to a human agent" or "escalate to a person" can read to the agent as an instruction to stop and wait for someone, so the work item sits on that step with nobody expected to act. When the hand-off is a result for a later step or a person to pick up, say so and say to finish — for example, "In every case, including when Needs review is Yes, finish the step. A Yes is a recorded result, not a request for help." To have the work genuinely wait for a person, use a human approval gate rather than wording. See How an AI agent ends a run.

Each decision in a workflow — does this customer already exist, do these two names match, is this request in scope — should be made by exactly one step. When two steps' instructions both decide the same thing, they will sooner or later reach different answers, and the work item ends up contradicting itself. Let one step decide and record the answer in a property, and have later steps read that property.

Reference the specific file or example to use — for instance, "map each expense to a category using the accounting-codes spreadsheet linked here." Linking the exact reference material is more reliable than describing it. When a pattern is easier to show than to describe (a sample input, an annotated document, an exact output format), add it as a positive or negative Example.

If a step only does internal work, do not use its instructions to describe messages to a person. Whether a chat step replies at all is controlled by its output properties and the conversation's settings. See AI Instructions for how a step sends a message on a chat workflow.

A custom AI tool's instructions are written to the same guidelines as a step's Directions. The tool's name, description, inputs and outputs play the part a step's properties and tools play for a step. Refer to the tool's inputs and outputs by their names, and make sure the instructions still produce every declared output.

Before you move on, check that the instructions: