> ## Documentation Index
> Fetch the complete documentation index at: https://docs.typewise.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Writing good Specialists

> What to put in each Specialist field so tickets reach the right one and get resolved

The [Specialists](/documentation/behavior/specialists) page shows how to create
a Specialist. This page is about what to write in its four fields: the name,
**When to use**, **Instructions**, and **Handoff conditions**. Each does a
different job, and the AI Agent reads it at a different moment.

## The When to use field

This is the field the AI Agent uses to pick a Specialist. When a ticket arrives
it sees the name and **When to use** of every active Specialist, and nothing
else.

Its job is to separate this Specialist from its neighbours. Where two of them
overlap, the AI has to guess. Say what the Specialist covers, then say what it
does not, and name the borderline cases that belong somewhere else.

**Too vague**

> * When a customer asks about a damaged product
> * When a customer wants to return something
> * When a customer has a problem with their order

**Specific enough**

> Handles complaints about products that arrived damaged, faulty, or not as
> described, including warranty claims. Not for undamaged returns, missing
> items, delivery status, or size advice.

Steps do not belong here. This field decides which Specialist takes the ticket,
and what happens next goes in the instructions. If no Specialist matches, the
ticket is handled as a general request, or handed off when
[Ticket handling](/documentation/behavior/company#ticket-handling) is set to
Specialists only.

## The Instructions field

Once the AI has picked a Specialist, it reads that Specialist's instructions and
handoff conditions in full, and can use every tool mentioned with `@` in them.

The AI follows these literally. Vague wording like "handle it appropriately"
gives you vague behaviour. A rigid script has the opposite problem. It covers
the tickets you thought of and leaves the AI improvising on everything else. Say
what the outcome should be, then give rules for the cases you can predict.

* **One step per bullet**, with the condition that triggers it and what the AI
  should do. Nest the sub-cases under the step they belong to. A flat list of
  the same content sends more tickets to the wrong Specialist.
* **Mention every tool the AI needs with `@`**: Actions, Lookups, and Knowledge
  sources. A tool named in plain text cannot be called. This is the single
  biggest thing you can fix in a Specialist.
* **Say what to do when a lookup comes back empty**, or when something you
  assumed turns out not to be true. "If the terms do not state a warranty
  period, do not quote one and continue with the claim." Anything you leave out
  is decided by the AI's judgement rather than yours.
* **Say what finished looks like.** "Once you have the order and a description
  of the fault, create the claim." That tells the AI when to stop, and gives it
  something to aim for on a ticket the instructions do not quite cover.
* **Keep "always" and "never" for rules with no exceptions**, such as safety or
  legal wording.
* **Say what to do rather than what to avoid**, where you can. "Check what you
  know against your tools, or ask the customer" works better than "do not make
  assumptions".
* **Shorter is usually better.** The best Specialists are rarely the longest.

You do not have to repeat rules that apply everywhere.
[Company configuration](/documentation/behavior/company) and channel guidelines
sit on top of every Specialist, so each one only covers its own topic.

<Tip>
  Some Specialists exist only to collect details and raise a [manual
  action](/documentation/actions/manual-actions) for a human, for example
  address changes where no integration exists. That is a good design. Write the
  instructions to gather exactly what the human needs, then use the manual
  action.
</Tip>

## The Handoff conditions field

These decide when the AI stops and brings in a Human Agent. It reads them
alongside the instructions and keeps applying them as the conversation goes on,
so each one has to be something it can actually observe in the conversation or
in a lookup result.

* **Observable facts, not moods.** "The customer still asks for a refund after
  the standard answer." "The case covers more than one order." Anger and direct
  requests for a human belong in the company-wide
  [handoff conditions](/documentation/behavior/company#handoff-conditions),
  where they apply everywhere.
* **Do not repeat When to use.** If everything the Specialist handles is also a
  handoff condition, it hands off every ticket before it replies.
* **Include "do not hand off when" rules.** "A customer profile that is not
  found is missing data, not a reason to hand off." A handful of sharp
  conditions plus a few exceptions works better than a long list.

This field takes prose only, so the `@` picker is not available here. To force a
handoff at one specific point, put **@Handoff to human agent** in the
instructions instead. Some topics hand off most of their tickets by design,
which is fine when it is deliberate.

## Put these somewhere else

| Content                                          | Where it belongs                                                                                                                                                                                              |
| :----------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Tone, greeting, emoji, reply length, language    | Channel guidelines for [Chat](/documentation/behavior/chat#channel-guidelines), [Email](/documentation/behavior/email#channel-guidelines), or [WhatsApp](/documentation/behavior/whatsapp#channel-guidelines) |
| Signatures and reply templates                   | [Email signatures](/documentation/behavior/email#signatures) and channel guidelines                                                                                                                           |
| Rules for every ticket, company facts            | [Global guidelines](/documentation/behavior/company#global-guidelines)                                                                                                                                        |
| "Customer is angry", "customer asks for a human" | Company [handoff conditions](/documentation/behavior/company#handoff-conditions)                                                                                                                              |

## Fix common problems

| Symptom                                                 | Likely cause                                               | Fix                                                        |
| :------------------------------------------------------ | :--------------------------------------------------------- | :--------------------------------------------------------- |
| Tickets on this topic land in a sibling or the fallback | When to use overlaps with another Specialist               | Say what this Specialist does not cover                    |
| Nearly every ticket is handed off before a reply        | Handoff conditions repeat the When to use field            | Keep the exceptions only, and add "do not hand off when"   |
| The AI asks a human to look something up                | The source is named in text, not added with `@`            | Add the mention at that step                               |
| Resolution rate is high, ratings are low                | Instructions close the conversation instead of handing off | Close only after the customer confirms, otherwise hand off |

## Worked example: warranty claims

A consumer electronics shop with an order lookup, a warranty terms document, and
an integration that creates claims.

<Card title="Name">Warranty claims</Card>

<Card title="When to use">
  Handles claims for products that stopped working or arrived faulty within the
  warranty period, including repair, replacement, and how to send a device in.
  Not for undamaged returns, order status, missing parcels, or questions about
  using a working device.
</Card>

<Card title="Instructions">
  * Find the purchase with **@Lookup: Order history** using the order number or
    the customer's email address.
    * If no order is found, ask for the order number or the email used at
      checkout, and nothing else.
  * Check the warranty period for the product category in **@Knowledge: Warranty
    terms**.
    * If the terms do not state a period for this product, do not quote one.
      Continue with the claim and say that the service team will confirm it.
  * If the purchase is outside the warranty period, say so, give the
    out-of-warranty repair option from **@Knowledge: Warranty terms**, and stop.
  * If the purchase is within warranty, collect what is still missing in one
    reply: a short description of the fault, when it started, and a photo or video
    if the fault is visible.
  * Once you have the order and the fault description, create the claim with
    **@Action: Create warranty claim** and tell the customer the claim number and
    what happens next.
</Card>

<Card title="Handoff conditions">
  * The customer reports smoke, fire, a burning smell, or an injury from the
    device.
  * The customer asks for a refund instead of a repair or replacement.
  * The claim covers more than one order.
  * The customer disputes the warranty period after you have quoted it.
  * Do not hand off because the order is not found on the first try, or because no
    photo was attached.
</Card>

## Test it

Create an [Automated Test](/documentation/testing-and-feedback/tests) for the
main path and one for each handoff condition. A test can assert which Specialist
handled the conversation, which tools were called, and whether a handoff
happened. Nova can
[draft a test from a real ticket](/documentation/nova/what-nova-can-do#testing).