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

# Tool Calls

> Let your agent perform specific actions during a call using tool calls.

Tool calls let your agent **perform specific actions during a call** like ending the conversation, scheduling a callback, waiting for the customer, or calling an external API.

## Quick Start

<Steps>
  <Step title="Reference a tool in your prompt">
    Prefix the tool name with `@` to reference it: `@toolName`. Tools that support multiple configured instances `@collect_data` and `@transferCall` take a colon-suffixed identifier picking the specific instance, e.g. `@collect_data:email` or `@transferCall:sales`. The Builder's tools sidebar inserts the correct reference for you.
  </Step>

  <Step title="Define when to use it">
    In your system prompt, clearly explain when the agent should (and shouldn't) use the tool
  </Step>

  <Step title="The agent handles the rest">
    During calls, the agent will trigger the tool when appropriate the customer never hears the tool name
  </Step>
</Steps>

<Note>
  In the prompt, define **when** the agent should use a tool not how the tool works technically. The technical configuration is handled separately in the agent settings.
</Note>

***

<Tabs>
  <Tab title="How Tool Calls Work">
    1. **The agent decides** Based on your prompt instructions, the LLM determines a tool should be called
    2. **The tool executes** The tool runs in the background; the customer never sees or hears the tool name
    3. **The agent continues** The agent receives the result and continues the conversation naturally
  </Tab>

  <Tab title="Built-in Tools">
    These tools are available to every agent out of the box:

    | **Tool**                   | **What It Does**                               |
    | :------------------------- | :--------------------------------------------- |
    | **`@endCall`**             | Ends the call                                  |
    | **`@callMeLater`**         | Schedules a callback at a later time           |
    | **`@waitForUserToReturn`** | Pauses and waits for the customer to come back |
    | **`@searchKnowledgeBase`** | Searches the agent's knowledge base            |
  </Tab>

  <Tab title="Custom HTTP Tools">
    Custom tools allow your agent to call external APIs during a conversation for example, looking up an account balance, checking appointment availability, or updating a CRM record.

    Custom tools are configured in the **Tools** section of your agent settings. See [Custom HTTP Tools](/custom-tools) for setup instructions.

    **How to Prompt Custom Tools**

    To help agents clearly understand **when and how to use tool calls**, each tool includes a **"Description"** (Global tool prompt) tab within its configuration page. There is also an LLM Variable prompt which can reference previous tool calls or define format.

    A detailed description:

    * Clearly explains **when** the tool should be used
    * Defines **how** it should be used
    * Specifies any important conditions, constraints, or input expectations
    * Reduces ambiguity for the agent

    Additionally, the description provides important context to the **system prompt**, helping the system better understand the intended use case and triggering logic of the tool.
  </Tab>
</Tabs>

***

<Tabs>
  <Tab title="Best Practices for Prompting Tool Usage">
    **Define When to Use**

    For each tool, clearly define in the system prompt:

    **→ When** the agent should use it

    **→ When** the agent should **not** use it

    **→ What to say** to the customer before/after using it (if anything)

    ***

    **Never Speak Tool Names Out Loud**

    Tool references in square brackets `[]` are internal actions. The customer only hears the natural-language result.

    <Warning>
      **Don't say:** *"I'm now calling the searchKnowledgeBase tool"*

      The customer shouldn't hear technical tool names.
    </Warning>

    <Check>
      **Do say:** *"Let me quickly look that up for you..."*

      Keep it natural and conversational.
    </Check>

    ***

    **Place Instructions Close to Usage**

    If a tool is related to a specific section of your script (e.g., knowledge base search is related to troubleshooting), put the usage instructions in that section not buried in a generic rules list far away.

    ***

    **Give Concrete Examples**

    Don't just say "use the knowledge base with Artikelnummer." Show the agent exactly what a correct query looks like.

    <Warning>
      **Don't write:** *"Use Artikelnummer when in the installation flow"*

      Too vague the agent doesn't know the exact format.
    </Warning>

    <Check>
      **Do write:** *"When the customer is in the installation flow, always include the article number in your search query. Example: **`fulltext_query: 'Artikelnummer 000012345 Sky Stream Installation kein Bild'`***"

      Clear, specific, with a concrete example.
    </Check>

    ***

    **Define Negative Cases**

    For every "when to use," also define "when NOT to use." This prevents the agent from over-using or mis-using tools.
  </Tab>

  <Tab title="Example Usage Rules">
    | **Tool**                   | **Action**                 | **Usage Rules**                                                                                                                                                                                                        | **Example Situation**                                               |
    | :------------------------- | :------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------ |
    | **`@endCall`**             | Agent ends the call        | Only after all tasks are completed and the conversation is fully concluded.                                                                                                                                            | The right person is not available                                   |
    | **`@callMeLater`**         | Agent schedules a callback | **Always** ask the customer first if they want a callback. Never call the tool before asking. Never use for expert callbacks. If the words "expert," "colleague," or "transfer" were used, this tool is **forbidden**. | The user is busy and wants to be called back later                  |
    | **`@waitForUserToReturn`** | Waits for the customer     | Use when giving instructions and waiting for the customer to act, or when the customer asks you to wait.                                                                                                               | Agent: "Plug in the cable." User: "One moment, I'll be right back." |
    | **`@searchKnowledgeBase`** | Searches knowledge base    | Use before giving technical instructions. Never use after already giving instructions.                                                                                                                                 | Customer asks a product question not covered in the prompt          |
  </Tab>
</Tabs>