Guide the assistant to use visuals – Applaud Support

Write agent instructions that tell collaborator agents when to display cards, lists, charts, maps, carousels, and organization charts.

Attaching Send Visual tools makes visual capabilities available to an agent. Your instructions tell the agent when to use each visual. Without clear instructions, the agent often returns plain text even when visual tools are attached.

Before you begin

Write effective visual instructions

Write instructions that answer three questions:

When should the agent use a visual instead of text?
Which visual type best fits each situation?
What information should the visual include, such as a title, list items, or actions?

Describe employee scenarios rather than tool names or implementation details. Focus on the outcome you want the employee to experience.

Prefer	Avoid
When the employee asks about onboarding tasks, send a checklist.	Use visuals whenever possible.
Show benefit plan options in a carousel.	Call send_visual_carousel.
Add an Open action when a policy or form URL is available.	Always include every action type.

Keep instructions concise

Effective instructions describe when to use each visual without explaining how the tools work.

Focus on employee scenarios rather than implementation details.
Avoid repeating the same guidance in different ways.
Use specific triggers rather than general statements, such as "use visuals whenever possible."
Let the visual present the detailed information and keep the conversational response brief.

Example: onboarding and benefits collaborator

Use the following example as a starting point for a collaborator agent that supports onboarding and benefits. Paste it into the Instructions field, then adapt names, links, and policies for your organization.

Note: Attach at least Send Visual — Card, Send Visual — List, Send Visual — Carousel, Send Visual — Chart, and Send Visual — Map if the agent provides office or event locations.

You help employees with onboarding and benefits. Use a visual when it communicates structured information more clearly than text alone. Keep your conversational reply to one or two sentences and let the visual present the detail.

## When to use each visual

- Card — one announcement, deadline, or policy highlight (for example, open enrollment dates). Include a clear title, optional chips for due dates, and an Open action when a trusted policy or form URL is available.
- List (checklist) — onboarding or benefits tasks with status. Use done, current, and pending. Do not invent completed tasks. Ask for clarification if status is unknown.
- List (stepper) — a fixed sequence of steps the employee must complete in order.
- Carousel — two to five comparable options (for example, medical plans). Use one card per option, with a title, a short description, and a Reply action, so the employee can choose within the conversation.
- Chart — numeric comparisons the employee requested (for example, enrollment counts or contribution amounts). Prefer simple bar or donut charts. Include a headline metric when one value is most important.
- Map — office, clinic, or enrollment event locations when the employee asks where to go. Include only locations that have reliable address or coordinate information.

## When to respond with text

- Simple yes/no or one-sentence answers
- Clarifying questions before enough information is available to build a visual
- Sensitive personal information that shouldn't appear on a shareable visual

## Actions

- Use **Open** for trusted intranet or policy pages.
- Use **Reply** or **Reply and send** when the next step is a short response the employee can send immediately (for example, "I'd like the PPO plan.").
- Never invent URLs. If you don't have a trusted link, omit the action.

## Tone

Write titles and labels in plain language. Don't mention tool names, schemas, or "visual cards" to the employee.

Why these instructions work

Instruction pattern	Effect
Starts with employee scenarios	Helps the agent match real questions to the appropriate visual.
Maps each visual to a specific purpose	Reduces incorrect visual choices.
Explains when to use text instead	Prevents unnecessary visuals for simple responses.
Controls actions and data	Avoids invented links and unnecessary information sharing.
Keeps the conversational reply short	Lets the visual and message complement each other.

Example: workflow agent step

Keep workflow agent instructions focused on the current step.

In this step, collect the employee's preferred work location and confirm nearby hubs.

When presenting hub options, send a Map with each hub shown as a pin, including the hub name and city. Add a short Reply action so the employee can choose a preferred hub.

If only one hub applies, send a Card with the hub name and address, and include an Open action to the site page when a trusted link is available. Don't send charts or carousels in this step.

Choose the right visual

Employee need	Prefer
One announcement or detail	Card
Tasks or ordered steps	List (checklist or stepper)
Several options to compare	Carousel
Numbers and trends	Chart
Places	Map
Reporting relationships	Organization chart
Process or decision flow	Mermaid diagram in the message (no visual tool required)

Tips for better results

Attach only the Send Visual tools the agent needs. Unused tools make tool selection less predictable.
Place visual guidance near the beginning of the Instructions field so it isn't buried beneath other guidance.
Test with realistic employee questions, such as:
- "What are my onboarding tasks?"
- "Compare the medical plans."
- "Where is the Austin office?"
If the agent continues to return text, make the trigger more specific, for example, "When the employee asks for onboarding tasks, send a checklist." Also confirm that the required tools are attached and that you published any workflow changes.

Note: Celebration visuals are configured separately. Don't include celebration guidance in collaborator agent instructions. Instead, enable Ovation mode on the orchestrator agent.

Related to