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

# Prompting Agents for Tools

> How to write persona instructions that guide the AI to use built-in tools effectively

## Overview

When you attach tools to a persona, the AI automatically knows they exist. However, **your system prompt determines when and how the agent uses them**. A well-written prompt tells the agent the conditions under which to invoke each tool.

You reference tools by their **model-facing name** in your persona instructions. These are the names the AI actually sees and calls.

***

## Voice Tools

These are available during live calls (`voice:in-call`).

### `hangUp`

Ends the call.

| Parameter | Type   | Required | Description                   |
| --------- | ------ | -------- | ----------------------------- |
| `reason`  | string | No       | A brief reason for hanging up |

```text theme={null}
Once you've confirmed the appointment and said goodbye, use hangUp to end the call.
Do not hang up while the customer is still speaking.
```

***

### `transferCall`

Transfers the call to another party. Used for both warm and cold transfers — the behavior depends on how the tool is configured on the persona.

**Warm transfer** (AI stays on the line during handoff):

| Parameter | Type   | Required          | Description                                                                                                     |
| --------- | ------ | ----------------- | --------------------------------------------------------------------------------------------------------------- |
| `target`  | string | Depends on config | The transfer destination (phone number or SIP URI). Only provided by the AI if configured with dynamic targets. |
| `context` | string | No                | Context from the conversation to share with the new party                                                       |

**Cold transfer** (immediate transfer, AI disconnects):

| Parameter | Type   | Required          | Description                                                                           |
| --------- | ------ | ----------------- | ------------------------------------------------------------------------------------- |
| `target`  | string | Depends on config | The transfer destination. Only provided by the AI if configured with dynamic targets. |

<Info>
  When the transfer target is pre-configured (static), the AI does not need to provide `target` — it's injected automatically. When configured with dynamic targets, the AI decides where to transfer based on the conversation.
</Info>

```text theme={null}
If the caller asks to speak with a manager, use transferCall and provide context
about what the caller needs help with.

If the caller requests the billing department, use transferCall to connect them.
Let them know you're transferring before you do it.
```

***

### `leaveVoicemail`

Leaves a voicemail and ends the call.

| Parameter | Type   | Required | Description                    |
| --------- | ------ | -------- | ------------------------------ |
| `message` | string | Yes      | The voicemail message to leave |

```text theme={null}
If the call goes to voicemail, use leaveVoicemail with a brief message:
introduce yourself, state the reason for calling, and leave a callback number.
Keep it under 30 seconds.
```

***

### `playDtmfSounds`

Plays touch-tone digits. Useful when your agent needs to navigate phone menus (IVR systems).

| Parameter | Type   | Required | Description                                        |
| --------- | ------ | -------- | -------------------------------------------------- |
| `digits`  | string | Yes      | The digits to play. May include `0-9`, `*`, or `#` |

```text theme={null}
When you reach the automated menu, use playDtmfSounds to press 2 for sales.
If prompted for an extension, dial 4501.
```

***

### `queryCorpus`

Searches the attached knowledge base for relevant information.

| Parameter     | Type    | Required | Description                                  |
| ------------- | ------- | -------- | -------------------------------------------- |
| `query`       | string  | Yes      | What to search for                           |
| `max_results` | integer | No       | How many results to return (1-20, default 5) |

<Info>
  This tool is automatically available when a knowledge base is attached to the persona. You don't need to manually enable it.
</Info>

```text theme={null}
If the caller asks a question about our policies or pricing, use queryCorpus
to look up the answer before responding. Don't guess — always check the knowledge base first.
```

***

## Multi-Agent Tools

### `agent_transfer`

Transfers the live call to a different AI persona mid-call. The new persona takes over with its own system prompt, voice, and tools.

| Parameter         | Type   | Required | Description                                                                      |
| ----------------- | ------ | -------- | -------------------------------------------------------------------------------- |
| `target_key`      | string | Yes      | Key of the target persona to transfer to (matches one of the configured targets) |
| `handoff_message` | string | No       | One-line context to share with the new agent                                     |

```text theme={null}
If the caller wants to discuss a technical issue, use agent_transfer with
target_key "technical_support" and include a handoff_message summarizing
what the caller needs. Let the caller know you're connecting them with a specialist.
```

***

### `create_call`

Creates a new outbound call as a separate session. Does not affect the current call.

| Parameter            | Type   | Required | Description                                                    |
| -------------------- | ------ | -------- | -------------------------------------------------------------- |
| `phone_number`       | string | No       | E.164 phone number to call (provide if no contact\_id)         |
| `contact_id`         | string | No       | Existing contact ID to call                                    |
| `persona_id`         | string | No       | Persona to make the call (defaults to configured persona)      |
| `context`            | string | No       | Reason/context for the call, shared with the receiving persona |
| `external_reference` | string | No       | Optional external reference for tracking                       |

```text theme={null}
If the customer asks you to call their colleague to confirm availability,
use create_call with the colleague's phone number and provide context about
why you're calling them.
```

***

## Prompting Best Practices

<AccordionGroup>
  <Accordion title="Be specific about when to use a tool">
    Don't just say "transfer if needed." Specify the exact conditions:

    ```text theme={null}
    Use transferCall if the caller explicitly asks for a human agent,
    or if you cannot resolve their issue after two attempts.
    ```
  </Accordion>

  <Accordion title="Tell the agent what to say before using a tool">
    The agent should communicate with the caller before taking action:

    ```text theme={null}
    Before using transferCall, always tell the caller:
    "Let me connect you with our billing team now."
    ```
  </Accordion>

  <Accordion title="Set guardrails on when NOT to use a tool">
    Prevent unwanted behavior by being explicit about restrictions:

    ```text theme={null}
    Never use hangUp while the customer is mid-sentence.
    Only hang up after they've confirmed they have no further questions.
    ```
  </Accordion>

  <Accordion title="Combine tools in sequences">
    You can instruct the agent to use multiple tools in order:

    ```text theme={null}
    When the caller needs to be transferred:
    1. Confirm with the caller that you're transferring them
    2. Use transferCall and provide context about what they need help with
    ```
  </Accordion>

  <Accordion title="Reference tool names exactly as shown">
    Always use the exact model-facing name (e.g., `transferCall`, not "transfer the call" or "do a warm transfer"). The AI maps your instructions to the tool by its name.
  </Accordion>
</AccordionGroup>