# Overview

Tools enhance your AI by connecting it to various apps and services, enabling it to fetch real-time information, update your CRM, send notifications, and much more. They keep your AI up to date and help you get things done efficiently!

## How to create a tool

Tools are contained within your project to ensure that sensitive tools aren’t accidentally activated in public projects. You can create a custom tool directly within your project or start with one of our templates.

A custom tool relies on an API request executed by the AI model. You can set this up easily using our step-by-step wizard in just 3 simple steps.

### Tool Prompts

* **Name:** Give your tool a unique name within your project.
* **Description:** Clearly explain what your tool does and what kind of response it will generate.
* **When to Call:** Specify exactly when the model should use this tool.

Example:

```
name: "get_current_weather"
description: "Get the current weather in a given location"
when to call: "When the users ask for the weather use get_current_weather"
```

### Parameters

Specify the parameters your AI model must provide to your tool. These parameters are defined using a [JSON schema](https://json-schema.org/), allowing you to leverage its rich features for validation and structure.

If no parameters are defined, the AI model will execute your tool without passing any parameters.

{% content-ref url="parameters" %}
[parameters](https://developers.chathive.app/tools/parameters)
{% endcontent-ref %}

### API configuration

In the final step, you can configure your API using our **API builder**.

![Screenshot of the api tool setup with a example how to use template variable in the url field and body](https://382411756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fx5Kure6K0P0mTPmH9FQb%2Fuploads%2FCHfddlknqLEQaMdWiu0J%2FScreenshot%202025-02-19%20at%2010.48.16.png?alt=media\&token=51cf0390-c909-4817-9df7-20412bc11ac5)<br>

By default, parameters are passed directly into the request body. However, you can override this with a custom request body if needed. This allows you to include additional information, such as conversation context or other values, without requiring the AI model to request them from the user.

#### Template variabels

In your API setup, you can use **variables** in the **URL**, **query parameters**, **headers**, and **body**. These templates will automatically be replaced with the corresponding values when the tool is called.

<table><thead><tr><th width="275.51702880859375">Template key</th><th>Description</th></tr></thead><tbody><tr><td>{{<em>parameter_key</em>}}</td><td>Access your parameters</td></tr><tr><td>{{context.<em>your_key</em>}}</td><td>Access the context you've provided to the SDK</td></tr><tr><td>{{customer.id}}</td><td>Get the id of the conversations customer</td></tr><tr><td>{{customer.email}}</td><td>Get the email of the conversations customer</td></tr><tr><td>{{customer.firstName}}</td><td>Get the first name of the conversations customer</td></tr><tr><td>{{customer.lastName}}</td><td>Get the last name of the conversations customer</td></tr><tr><td>{{customer.avatar}}</td><td>Get the avatar of the conversations customer</td></tr><tr><td>{{project._id}}</td><td>Get the id of the project</td></tr><tr><td>{{project.name}}</td><td>Get name of the project</td></tr><tr><td>{{organization._id}}</td><td>Get the organization id</td></tr><tr><td>{{organization.name}}</td><td>Get the name of the organization</td></tr><tr><td>{{conversation.language}}</td><td>Get the language of the conversation</td></tr><tr><td>{{conversation.sessionId}}</td><td>Get the sessionId of the conversation</td></tr><tr><td>{{conversation.createdAt}}</td><td>Get the datetime the conversation was created</td></tr><tr><td>{{conversation.updatedAt}}</td><td>Get the datetime the conversation was last updated</td></tr><tr><td>{{conversation.lastMessageAt}}</td><td>Get the datetime the last message was send</td></tr><tr><td>{{conversation.tagIds}}</td><td>Get <code>,</code> -seperated list with all tag ids in the conversation</td></tr></tbody></table>

### Response restrictions

#### Timeout

To keep your agents running smoothly, tools have a **5-minute** response window before timing out.\
We will lower this timeout in the future to improve performance.

#### Response size

To keep things running smoothly and avoid overloading the agent, there is a **25MB limit** on all responses. If a tool tries to return more data than that, the call will be stopped and the agent will receive an error message explaining that the response was too big.