> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ada.cx/docs/optimization/performance/intent-intelligence/best-practices/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server.

# Best practices

Improving your AI Agent starts with understanding how end users interact with it. Under **Analytics**, the **Topics & Intents** tab is especially valuable because it highlights where conversations cluster, how automation is performing, and where satisfaction may be slipping. Combined with other reporting tools, it gives AI Managers a clear path to identify gaps and prioritize improvements.

## Writing effective Topics and Intents \[#topic-best-practices]

Conversations are classified by the Intents within each Topic, so clear definitions help your AI Agent assign conversations accurately. Use Topics for broad subjects and Intents for the specific reasons behind a conversation.

### General guidelines

* **Be specific**: Use clear, specific language in your Topic and Intent definitions. This helps the AI Agent understand the reason behind an inquiry.
* **Structure from broad to specific**: Define a Topic for the subject (for example, *Billing*), then add Intents for the distinct reasons within it (for example, *Dispute a charge* and *Update payment method*).
* **Use included and excluded examples**: For each Intent, list phrases or situations to match under **What's included** and ones to keep out under **What's excluded**. This sharpens the boundary between similar Intents.

### Length and detail

* **Names**: Keep Topic and Intent names short and recognizable (up to 128 characters).
* **Descriptions**: Aim for concise descriptions (up to 1,024 characters) that make the scope of the Topic or Intent unambiguous.

### Continuous improvement

* **Monitor and adjust**: Regularly review performance and refine definitions based on end user interactions. If conversations aren't matching correctly, tighten the descriptions or the included and excluded examples.
* **Act on recommendations**: Review AI-recommended Intents to capture reasons your taxonomy is missing, then approve or dismiss them.

> **Note**
>
> When you edit a Topic or Intent definition, your AI Agent uses the updated information for new conversation assignments only. Existing assignments are not changed.

## Topic analysis examples

These examples can help you improve your AI Agent by revealing patterns in end user interactions. AI Managers can:

1. Start with the **Topics & Intents** tab to review key metrics like [Conversation](/docs/optimization/conversations) volume, AR Opportunity, and CSAT rate.
2. Use overall CSAT scores as another reference point — if CSAT is dropping, check the CSAT rate on the **Topics & Intents** tab.
3. Drill into related Conversations to find the issues behind poor CSAT and uncover automation gaps.

### Example: Refund requests \[#topics-example-refund-requests]

Use this scenario when a Topic shows high volume or a high **AR Opportunity**—especially for underserved user segments. In this case, a Topic analysis reveals that student users often ask for refunds but rarely receive helpful responses from the AI Agent.

**To investigate refund request Topics:**

1. On the Ada dashboard, go to **Analytics**.
2. On the **Topics & Intents** tab, look for a *Refund requests* Topic with high [Conversation](/docs/optimization/conversations) volume and a high AR Opportunity rate.
3. Drill into the Topic and review related Conversations. You notice student users frequently ask how to get a refund for purchases made through third-party vendors.
4. The Agent responds with a generic message or hands off the conversation because no relevant [Knowledge](/docs/knowledge) article exists.

![](/_fern-img/0ae16931ed5b4911340c76c2f7ce9157dd6809774f150f62d4a1ca7e9e173f87.webp)

> **Tip**
>
> The Agent uses **the same language for all users**, even though student users may be less familiar with refund policies or know what to expect from support.

These Conversations often end in unnecessary [Handoffs](/docs/handoffs) that could be avoided with better guidance.

**Next steps:**

1. Add a [Knowledge](/docs/knowledge) article tailored to student users that explains how to request a refund from an external vendor. For example:

![](/_fern-img/18cd745eb6d95c65c4845d7f9700575d53283a29e03f14d5c48d5971a8802b25.webp)

2. Apply [Personalization](/docs/optimization/personalization/personalization-data) rules to adjust tone and messaging for student accounts—creating a more relevant, accessible experience that supports self-serve resolution. For example:

![](/_fern-img/b96f312d3b9dc23efe5f99ed1317dccc032266bb9e448726ec01e2b1a0a0a615.webp)

### Example: Card fulfillment \[#topics-example-card-fulfillment]

Use this scenario when a Topic shows moderate automation but a high **AR Opportunity**—suggesting the AI Agent is initiating the right flow but consistently [handing off](/docs/handoffs) where automation could continue.

**To investigate card fulfillment Topics:**

1. On the Ada dashboard, go to **Analytics**.
2. On the **Topics & Intents** tab, identify a *Card fulfillment* Topic with high AR Opportunity rate.
3. Drill into the Topic and review [Conversations](/docs/optimization/conversations). You find a recurring pattern: the Agent checks shipment details, confirms the delivery address, and provides messaging based on how many days have passed.
4. However, if the end user needs to update their address or request a new card, the Agent always hands off—even though this could be automated.

![](/_fern-img/8d76e7c1d0b476dce5f5f40d114343afa55c1e173af099e991fedf8884eb755d.webp)

**Next steps:**

1. Add [Coaching](/docs/optimization/coaching) to refine the Agent's messaging and ensure the end user receives clear, actionable next steps.

   ![](/_fern-img/9cec22fdba53748b300ec73e612dd2764cb2c566bcb945188bec32be6ea3a63a.webp)

2. Build an [Action](/docs/automation/tools/api-tools) to automate common fulfillment requests like reshipments or address changes—reducing premature handoffs and improving resolution rates.

![](/_fern-img/462801efc7c6ffbee8fa499900582872add3405081d0b876de6fb772dabaa685.webp)

### Example: Account cancellation \[#csat-example-account-cancellation]

In the [Customer Satisfaction Score](/docs/optimization/performance/csat-survey/csat-survey-configuration) report, you notice a drop in the **Overall Score**.

![](/_fern-img/f284c42512b0512f35e7e12592dbad9e1f37348e9f2d938bc1e62480a3f4b312.webp)

To investigate, navigate to the **Analytics**, and on the **Topics & Intents** tab, sort by **CSAT** rate—where a Topic related to subscription or account cancellation stands out with consistently low satisfaction. This signals a high-friction experience in a sensitive scenario.

Drilling into the related [Conversations](/docs/optimization/conversations) reveals a recurring pattern: the AI Agent detects the intent correctly but fails to guide end users through the next steps—resulting in confusion, frustration, and low CSAT.

1. An end user asks to cancel their account or subscription.
2. The AI Agent detects the intent but responds with a generic message like *Let me connect you with support*, without acknowledging the request or providing guidance.
3. There's no attempt to explain the cancellation process, gather details, or offer relevant resources.
4. As a result, the Conversation is handed off immediately—leaving the end user dissatisfied.

**Next steps:**

1. Create or refine a [Knowledge](/docs/knowledge) article that outlines the cancellation process in simple, direct language. Include details based on plan types or support policies to improve clarity.
2. Use [Coaching](/docs/optimization/coaching) to train the AI Agent to acknowledge cancellation requests clearly and provide pre-escalation guidance that sets expectations.

![](/_fern-img/6d0415d0ec36390a705cdd005a405542da2cb504256ab5e2316fafc7e62af2f5.webp)

These updates will help reduce premature [Handoffs](/docs/handoffs), improve CSAT, and ensure end users feel understood and supported at a critical moment.

### Example: Warranty replacement \[#csat-example-warranty-replacement]

Start by reviewing the entries on the **Topics & Intents** tab and sorting by the **CSAT** rate. You notice that Topics like *Replacements* or *Damaged products* are performing poorly, with consistently low satisfaction scores.

![](/_fern-img/7669e332ed430bd3fe582fd8e5723bd2f7567a09af3d4ebc04c9a3264a7e95b8.webp)

Drilling into one of these Topics reveals a common pattern: the AI Agent recognizes the intent but lacks the ability to collect the required details—resulting in early handoffs and a missed opportunity to automate the experience.

1. An end user requests a replacement for a damaged product under warranty.
2. The Agent acknowledges the request but doesn't collect critical information like purchase date, product model, or description of the issue.
3. Because these inputs are necessary to check eligibility, the Agent hands off the conversation prematurely.
4. The Agent also uses the same communication style for all end users, missing the chance to personalize the response based on the end user's plan (e.g., *Premium* support) or region.

**Next steps:**

1. Build a [Playbook](/docs/automation/playbooks) that gathers all required inputs, checks warranty eligibility through an [Action](/docs/automation/tools/api-tools), and either submits the replacement request or provides clear next steps if ineligible.

   ![](/_fern-img/cd79c8363e980c6c298ddc0751c4914b545b015211fbba3a16cb9b2ab3bc98e5.webp)

2. Apply [Personalization](/docs/optimization/personalization/personalization-data) rules to tailor messaging by user segment—such as using elevated tone for premium members or adding shipping timelines based on region.

   ![](/_fern-img/cc357e650b93576b2831fff841a54ec3d6ebb1745e4ccf6b868232d04463eba5.webp)

These improvements reduce [Handoffs](/docs/handoffs), streamline the replacement workflow, and create a more supportive, tailored experience for end users.

---

Have any questions? Contact your Ada team, or email us at [](mailto:help@ada.cx?subject=Help%20Docs%20inquiry).