Writing Block Descriptions

When you organize your AI's instructions into blocks, each block has a description — the small "When to run this block" line at the top. This is how your AI knows which block to use for each customer message.

Get descriptions right and your AI picks the right block every time. Get them wrong and customers can end up with the wrong answer — or no answer at all.

What a description is

The description is your note to the AI about when to follow this block. It's not the title (that's just for you), and it's not the instructions themselves. It's the answer to: "What kind of customer message should make my AI use this block?"

Think of it like a sticky note on a folder of instructions:

• Title — the folder name (for you)
• Description — the sticky note that says "open me when…"
• Instructions — what's inside the folder

Your AI reads the sticky note. It doesn't read the folder name.

Why descriptions matter

For every customer message, your AI scans your block descriptions and picks the one that best fits the situation. If your description is clear and specific, the right block fires. If it's vague or overlaps with another block, your AI may pick the wrong one — or skip them all and fall back to a generic response.

Three rules for writing good descriptions

1. Describe the situation, not the topic

A topic is a category. A situation is what's actually happening in the conversation. Your AI matches by situation.

Topics are too short and too broad — they could apply to almost any message. Situations give your AI something concrete to match against.

2. Cover the words your customers actually use

Customers don't phrase things the way you write them. A good description packs one or two natural phrasings into a single sentence.

Too narrow:

"Customer wants a refund."

Covers paraphrases:

"Customer asks for a refund, says they want their money back, or disputes a charge on their card."

You don't need to list every possible phrase — just enough to anchor the meaning. Two or three natural variations is usually plenty.

3. Make every block clearly different from the others

If two blocks could both apply to the same message, your AI has to guess between them. Sometimes it'll get it right, sometimes it won't.

Test each pair: "If a customer says X, which block should fire — and only that one?"

If you find an overlap, narrow each description so the boundary is obvious.

Overlapping (both could fire on "why was I charged twice?"):

• Block A: "Customer asks about billing."
• Block B: "Customer asks about charges or payments."

Distinct:

• Block A: "Customer wants a refund or to be made whole financially."
• Block B: "Customer asks why a charge appeared but isn't asking for money back."

Common mistakes

Too generic

"When the customer needs help."

This matches almost anything, so your AI can't use it confidently. It'll likely be skipped.

Just a label

"Pricing" or "Support"

Single-word descriptions don't tell your AI when to fire the block. Write a full sentence describing what the customer is doing or saying.

Two situations crammed in

"Customer wants to cancel or upgrade their plan."

These are two completely different conversations — they should be two separate blocks. Combining them confuses your AI and produces vague matches for both cases.

Internal jargon

"MRR churn event in progress."

Customers don't talk that way. Write descriptions in the same plain language your customers use.

Empty

Leaving the description blank makes the block unreliable. Every block needs a description to do its job.

Examples that work

Here are descriptions that follow all three rules:

• "Customer asks where their order is, when it will arrive, or for a tracking link."
• "Customer reports their package was damaged, missing, or never arrived."
• "Customer asks how to invite teammates, add users, or share their workspace."
• "New customer just signed up and is asking what to do first or how to get started."
• "Customer asks to cancel their subscription, end their plan, or stop being billed."
• "Customer wants to upgrade, change plans, or add seats to their account."
• "Customer asks for a refund or says they were charged incorrectly."
• "Customer asks to speak to a human, manager, or real person."

Each one reads like a real situation, includes a couple of natural phrasings, and doesn't overlap with the others.

Tips for great descriptions

• Brief them like a teammate. Imagine telling a new hire: "Use this when a customer…" The way you'd finish that sentence is your description.
• Read each one aloud. If it sounds like a filing label, rewrite it as a sentence about what's happening.
• Check for overlaps. Skim your full list of descriptions side by side. Any two that could both apply? Tighten or merge.
• Update as you learn. Real conversations surface phrasings you didn't anticipate. When you spot a missed match, add the new wording to the description.
• Keep it brief. One or two sentences is enough — long descriptions don't help and may dilute the meaning.

Troubleshooting

My block isn't firing when it should

The description is probably too generic, missing key phrasings, or overlapping with another block. Try:

• Rewriting it as a complete situational sentence
• Adding one or two of the actual phrases customers use
• Comparing it against your other block descriptions for overlap

A different block keeps firing instead

Two descriptions are likely too similar. Pick a message that's matching the wrong block and decide which block should handle it. Then narrow the other block's description so it no longer applies to that case.

My AI keeps falling back to a generic answer

Your descriptions may be too vague across the board. Test in the playground with real example messages, see which blocks should be firing, and rewrite the descriptions that aren't catching what they should.

What's next?

• AI Agent setup — Configure your persona end to end
• FAQ Management — Handle common questions
• Knowledge Base — Teach your agent what it needs to know