# 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="/pages/cJCkyXJBkEGTWSHC0ctM" %}
[Parameters](/tools/parameters.md)
{% 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](/files/qfJPgCgkxk4kLU68s9mQ)<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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.chathive.app/tools/overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.