Prompt Engineering Basics for AI Agents

An agent prompt is not a chat prompt. In chat the result is text and a human reads it. For an agent the result is a choice of action and a program executes it.

What actually drives the result

In descending order of impact:

1. Tool descriptions. They are how the agent picks an action. The biggest lever, and usually the least worked on.
2. Response format. An explicit schema with required fields removes half the parsing problems.
3. The definition of done. Without it the agent stops when it feels finished.
4. The rule for missing data. Unstated, and it will invent. That is default behaviour, not a malfunction.
5. Examples, especially edge cases.
6. The wording of the prompt itself. It matters, noticeably less than people assume.

What does not matter: politeness, exclamation marks, promised rewards, capitals. Folklore that occupies context.

System prompt structure

A structure that covers most cases:

Role and task. One paragraph: what this system is, what it does, for whom.

What is available. A short list of tools with a note on when each applies. Detail belongs in the tool descriptions; this is only a map.

Decision rules. How to act in typical situations and, above all, in ambiguous ones. Separately: what to do when data is missing. This is the most important item, because without it the model fills the gap with invention.

Boundaries. What never to do. With the caveat that this is default behaviour, not a guarantee. Real constraints live in permissions and missing tools - see rollout and guardrails.

Response format. An explicit schema. “Answer in JSON” without field definitions works worse than a schema that lists them.

Examples. Two or three, including one where the correct answer is a refusal or a handover.

Order matters: material at the beginning and end of a long prompt lands better than material in the middle.

Tool descriptions

This is where the real work sits, and where the corners get cut.

A good description answers four questions:

• What the tool does - one sentence.
• When to use it. Concretely: “when the message contains an order number”.
• When not to use it. The most frequently omitted item, and the one that prevents redundant calls.
• What comes back, including the “nothing found” case.

A bad description: “Order handling”. The agent will call it whenever the word “order” appears.

A good one: “Returns the status and contents of an order by its number. Use when the order number is known. Do not use to find a customer’s orders - there is a separate tool for that. If the order is not found, returns an empty result rather than an error.”

The second rule: one tool does one thing. A tool with a “mode” parameter taking five values is five tools the agent will confuse.

Common mistakes

• Constraints only in the prompt. “Do not delete data” is a wish. Remove the delete tool.
• No rule for missing data. The model fills the gap plausibly. Say explicitly: if data is missing, stop and report.
• A vague definition of done. “Handle the ticket” admits a dozen readings, and the agent takes the easiest.
• A prompt that grows by accretion. Every problem is patched with one more sentence, the prompt swells, contradictions pile up. Periodically it needs rewriting rather than appending.
• Client specifics in the shared prompt. It breaks other clients - see prompt layers.
• Changes without testing. An edit with no example set swaps one unknown accuracy for another.

The practical minimum

If you do only four things, do these:

1. Write tool descriptions a person who has never seen your system could follow.
2. Define an explicit response schema.
3. State what to do when data is missing.
4. Collect twenty examples and run them before and after every edit.

How this scales across several clients: layers instead of forks. The overview is in the AI agents guide.