Writing Better Instructions

By the end of this lesson, you will be able to:

• Explain the role instructions play in agent behavior

• Understand how instruction quality impacts output quality

• Write clearer, more effective instructions for common agent tasks

• Identify opportunities to refine instructions and improve results

• Apply instruction-writing best practices when building agents

Why Instructions Matter

If triggers determine when work begins and tools determine what capabilities are available, instructions determine what outcome the agent is trying to achieve.

Instructions are how we communicate our expectations to the agent.

They provide direction.

They define objectives.

They establish constraints.

Without instructions, an agent has no clear understanding of what success looks like.

Consider the difference between these two requests:

Generate tags for this article.

and

Generate 3-5 specific tags that accurately represent the primary themes of the article. Avoid generic tags unless they are central to the content.

Both requests ask the agent to generate tags.

One provides significantly more guidance.

As a result, the quality of the output is often very different.

Instructions Are Not Procedures

One of the most important ideas to understand is that instructions are not the same thing as traditional programming.

When writing instructions, you are usually defining outcomes rather than individual steps.

For example, a traditional workflow might specify:

• Read the article

• Identify key themes

• Generate a teaser

• Create SEO metadata

• Save the results

An agent is often capable of determining many of those steps on its own.

Instead of focusing exclusively on procedure, focus on the desired result.

For example:

Generate a teaser, SEO title, SEO description, and tags that accurately represent the content of the article.

This gives the agent a goal while allowing it to determine how best to achieve that outcome using the available tools.

Good Instructions Provide Context

Agents generally perform better when they understand the purpose behind a task.

Instead of simply saying:

Generate a teaser.

Consider providing additional context:

Generate a teaser that summarizes the article while encouraging readers to continue reading.

Now the agent understands not only what to generate, but why it is generating it.

This additional context often improves quality significantly.

Good Instructions Define Constraints

Constraints help establish expectations.

For example:

Weak Instruction

Generate an SEO description.

Better Instruction

Generate an SEO description between 140 and 160 characters.

The second version provides a measurable target.

Similarly:

Weak Instruction

Generate tags.

Better Instruction

Generate 3-5 specific tags that improve content discovery. Avoid generic tags unless they are central to the article.

The additional guidance reduces ambiguity and improves consistency.

Refinement Is Part of the Process

One of the most common misconceptions about agents is that the first output should always be perfect.

In reality, building agents is often an iterative process.

You review the output.

You identify opportunities for improvement.

You adjust the instructions.

Then you test again.

For example, imagine our Content Enrichment Agent generates these tags:

• Technology

• AI

• Content

These tags aren't incorrect.

But they're not particularly useful.

We might refine our instructions by adding:

Generate tags that are specific, reusable across multiple articles, and useful for content discovery. Avoid overly broad categories unless they are central to the article.

The result is often a much stronger set of tags.

Notice what changed.

We didn't modify the trigger.

We didn't change the tools.

We simply improved the instructions.

A Simple Framework for Writing Instructions

When creating instructions, consider the following framework:

Outcome

What should the agent accomplish?

Example:

Generate a teaser and SEO metadata.

Context

Why is the agent performing this task?

Example:

The metadata should improve discoverability and help readers understand the article.

Constraints

What rules should the agent follow?

Example:

Generate an SEO description between 140 and 160 characters.

When all three elements are present, the agent has a much clearer understanding of what success looks like.

The Instructions We'll Use

For our Content Enrichment Agent, we'll ask the agent to:

• Retrieve the article that triggered the workflow

• Analyze the content

• Generate a teaser

• Generate an SEO title

• Generate an SEO description

• Generate tags

• Update the content entry

• Notify the team when enrichment is complete

As we continue building, we'll refine these instructions and observe how those refinements influence the final output.

Key Takeaways

• Instructions define the outcome an agent should achieve.

• Better instructions generally produce better results.

• Focus on outcomes rather than detailed procedures whenever possible.

• Context helps agents understand why a task is being performed.

• Constraints help improve consistency and quality.

• Refinement is a normal part of agent development.

Next Lesson

Next, we'll apply these principles as we transform our article summary workflow into a complete Content Enrichment Agent that generates metadata, updates content entries, and prepares content for review.